@umituz/react-native-auth 3.4.31 → 3.4.33

package/src/presentation/hooks/useAuthBottomSheet.md

@@ -1,417 +1,464 @@
 # useAuthBottomSheet
 
-Authentication bottom sheet yönetimi için hook. Login/Register modal'ını göstermek, yönetmek ve social authentication işlemlerini gerçekleştirmek için kullanılır.
+Hook for authentication bottom sheet modal management.
 
-## Özellikler
+---
 
-- Bottom sheet modal yönetimi
-- Login/Register mod değiştirme
-- Social authentication entegrasyonu
-- Otomatik kapanma (başarılı authentication sonrası)
-- Pending callback yönetimi
+## Strategy
 
-## Kullanım
+**Purpose**: Manages authentication modal (bottom sheet) with login/register forms, social authentication, and auto-close behavior. Integrates with auth modal store for global state management.
 
+**When to Use**:
+- Need modal-based authentication flow
+- Want to show login/register on demand
+- Need social auth in modal
+- Want auto-close after successful auth
+- Require pending callback execution
+
+**Import Path**:
 ```typescript
 import { useAuthBottomSheet } from '@umituz/react-native-auth';
-import { BottomSheetModal } from '@umituz/react-native-design-system';
-
-function AuthBottomSheet() {
-  const {
-    modalRef,
-    mode,
-    providers,
-    googleLoading,
-    appleLoading,
-    handleDismiss,
-    handleClose,
-    handleNavigateToRegister,
-    handleNavigateToLogin,
-    handleGoogleSignIn,
-    handleAppleSignIn,
-  } = useAuthBottomSheet({
-    socialConfig: {
-      google: {
-        iosClientId: 'your-ios-client-id',
-        webClientId: 'your-web-client-id',
-      },
-      apple: { enabled: true },
-    },
-  });
-
-  return (
-    <BottomSheetModal ref={modalRef} onDismiss={handleDismiss}>
-      {mode === 'login' ? (
-        <LoginForm
-          onRegisterPress={handleNavigateToRegister}
-          onGoogleSignIn={handleGoogleSignIn}
-          onAppleSignIn={handleAppleSignIn}
-          googleLoading={googleLoading}
-          appleLoading={appleLoading}
-        />
-      ) : (
-        <RegisterForm
-          onLoginPress={handleNavigateToLogin}
-          onGoogleSignIn={handleGoogleSignIn}
-          onAppleSignIn={handleAppleSignIn}
-          googleLoading={googleLoading}
-          appleLoading={appleLoading}
-        />
-      )}
-    </BottomSheetModal>
-  );
-}
 ```
 
-## API
+**Hook Location**: `src/presentation/hooks/useAuthBottomSheet.ts`
 
-### Parameters
+**Modal Store**: `src/presentation/stores/authModalStore.ts`
 
-| Param | Tip | Required | Açıklama |
-|-------|------|----------|----------|
-| `socialConfig` | `SocialAuthConfiguration` | No | Social auth konfigürasyonu |
-| `onGoogleSignIn` | `() => Promise<void>` | No | Custom Google sign-in handler |
-| `onAppleSignIn` | `() => Promise<void>` | No | Custom Apple sign-in handler |
+**Modal Component**: `@umituz/react-native-design-system`'s `BottomSheetModal`
 
-#### SocialAuthConfiguration
+---
 
-```typescript
-interface SocialAuthConfiguration {
-  google?: GoogleAuthConfig;
-  apple?: { enabled: boolean };
-}
-```
+## Core Functionality
 
-### Return Value
+### Modal Reference
 
-| Prop | Tip | Açıklama |
-|------|-----|----------|
-| `modalRef` | `RefObject<BottomSheetModalRef>` | Bottom sheet modal referansı |
-| `mode` | `'login' \| 'register'` | Mevcut mod |
-| `providers` | `SocialAuthProvider[]` | Mevcut social provider'lar |
-| `googleLoading` | `boolean` | Google loading durumu |
-| `appleLoading` | `boolean` | Apple loading durumu |
-| `handleDismiss` | `() => void` | Modal'ı kapatma (dismiss) |
-| `handleClose` | `() => void` | Modal'ı kapatma ve temizleme |
-| `handleNavigateToRegister` | `() => void` | Register moduna geçiş |
-| `handleNavigateToLogin` | `() => void` | Login moduna geçiş |
-| `handleGoogleSignIn` | `() => Promise<void>` | Google ile giriş |
-| `handleAppleSignIn` | `() => Promise<void>` | Apple ile giriş |
+**Purpose**: Ref object for controlling bottom sheet modal.
 
-## Örnekler
+**PROPERTIES**:
+- Type: `RefObject<BottomSheetModalRef>`
+- Used to: Open, close, and control modal
 
-### Basit Auth Bottom Sheet
+**Rules**:
+- MUST pass to BottomSheetModal component
+- MUST use for programmatic control
+- MUST not create multiple refs
 
-```typescript
-function AuthModal() {
-  const {
-    modalRef,
-    mode,
-    handleDismiss,
-    handleNavigateToRegister,
-    handleNavigateToLogin,
-  } = useAuthBottomSheet();
-
-  return (
-    <BottomSheetModal ref={modalRef} snapPoints={['80%']} onDismiss={handleDismiss}>
-      <View>
-        {mode === 'login' ? (
-          <>
-            <Text>Giriş Yap</Text>
-            <LoginForm />
-            <Button onPress={handleNavigateToRegister}>
-              Hesabınız yok mu? Kayıt Olun
-            </Button>
-          </>
-        ) : (
-          <>
-            <Text>Kayıt Ol</Text>
-            <RegisterForm />
-            <Button onPress={handleNavigateToLogin}>
-              Zaten hesabınız var mı? Giriş Yapın
-            </Button>
-          </>
-        )}
-      </View>
-    </BottomSheetModal>
-  );
-}
-```
+**Constraints**:
+- Single modal instance
+- Managed by authModalStore
+- Ref persists across renders
 
-### Social Login ile
+---
 
-```typescript
-function AuthBottomSheetWithSocial() {
-  const {
-    modalRef,
-    mode,
-    providers,
-    googleLoading,
-    appleLoading,
-    handleDismiss,
-    handleNavigateToRegister,
-    handleNavigateToLogin,
-    handleGoogleSignIn,
-    handleAppleSignIn,
-  } = useAuthBottomSheet({
-    socialConfig: {
-      google: {
-        webClientId: Config.GOOGLE_WEB_CLIENT_ID,
-        iosClientId: Config.GOOGLE_IOS_CLIENT_ID,
-      },
-      apple: { enabled: Platform.OS === 'ios' },
-    },
-  });
-
-  return (
-    <BottomSheetModal ref={modalRef} snapPoints={['90%']} onDismiss={handleDismiss}>
-      <View>
-        {mode === 'login' ? (
-          <>
-            <LoginForm />
-
-            {/* Social login buttons */}
-            {providers.includes('google') && (
-              <SocialButton
-                provider="google"
-                onPress={handleGoogleSignIn}
-                loading={googleLoading}
-              />
-            )}
-
-            {providers.includes('apple') && (
-              <SocialButton
-                provider="apple"
-                onPress={handleAppleSignIn}
-                loading={appleLoading}
-              />
-            )}
-
-            <Button onPress={handleNavigateToRegister}>
-              Kayıt Ol
-            </Button>
-          </>
-        ) : (
-          <>
-            <RegisterForm />
-
-            {/* Social login buttons */}
-            {providers.includes('google') && (
-              <SocialButton
-                provider="google"
-                onPress={handleGoogleSignIn}
-                loading={googleLoading}
-              />
-            )}
-
-            {providers.includes('apple') && (
-              <SocialButton
-                provider="apple"
-                onPress={handleAppleSignIn}
-                loading={appleLoading}
-              />
-            )}
-
-            <Button onPress={handleNavigateToLogin}>
-              Giriş Yap
-            </Button>
-          </>
-        )}
-      </View>
-    </BottomSheetModal>
-  );
-}
-```
+### Mode Management
 
-### Custom Social Login Handlers
+**Purpose**: Tracks current modal mode (login or register).
 
-```typescript
-function AuthBottomSheetWithCustomHandlers() {
-  const { showAuthModal } = useAuthModalStore();
-
-  const handleCustomGoogleSignIn = async () => {
-    try {
-      // Custom Google sign-in logic
-      const result = await customGoogleSignInFlow();
-
-      if (result.success) {
-        // Başarılı authentication sonrası modal otomatik kapanır
-        console.log('Google ile giriş başarılı');
-      }
-    } catch (error) {
-      Alert.alert('Hata', 'Google ile giriş başarısız');
-    }
-  };
-
-  const handleCustomAppleSignIn = async () => {
-    try {
-      // Custom Apple sign-in logic
-      const result = await customAppleSignInFlow();
-
-      if (result.success) {
-        console.log('Apple ile giriş başarılı');
-      }
-    } catch (error) {
-      Alert.alert('Hata', 'Apple ile giriş başarısız');
-    }
-  };
-
-  const {
-    modalRef,
-    mode,
-    googleLoading,
-    appleLoading,
-    handleDismiss,
-    handleNavigateToRegister,
-    handleNavigateToLogin,
-    handleGoogleSignIn,
-    handleAppleSignIn,
-  } = useAuthBottomSheet({
-    onGoogleSignIn: handleCustomGoogleSignIn,
-    onAppleSignIn: handleCustomAppleSignIn,
-  });
-
-  return (
-    <BottomSheetModal ref={modalRef} onDismiss={handleDismiss}>
-      {/* Auth form content */}
-    </BottomSheetModal>
-  );
-}
-```
+**VALUES**:
+- `'login'` - Show login form
+- `'register'` - Show registration form
+
+**Rules**:
+- MUST display appropriate form based on mode
+- MUST switch forms when mode changes
+- MUST preserve mode during modal open
+- MUST reset to default on close
+
+**Constraints**:
+- Controlled by authModalStore
+- Default mode: `'login'`
+- Switchable via navigation handlers
+- Auto-reset on modal close
+
+---
+
+### Provider Detection
+
+**Purpose**: Automatically determines which social providers are available.
+
+**VALUES**:
+- Type: `SocialAuthProvider[]`
+- Possible: `['google']`, `['apple']`, `['google', 'apple']`, `[]`
+
+**Rules**:
+- MUST check provider availability
+- MUST respect platform limitations
+- MUST filter based on configuration
+- MUST update on config changes
+
+**Constraints**:
+- Platform-dependent:
+  - iOS: Google + Apple (if configured)
+  - Android: Google only
+  - Web: Google only
+- Configuration-dependent
+- Auto-calculated from config
+
+---
+
+## Navigation Handlers
+
+### handleNavigateToRegister
+
+**Purpose**: Switch modal from login to register mode.
+
+**Rules**:
+- MUST change mode to `'register'`
+- MUST keep modal open
+- MUST update form display
+
+**Constraints**:
+- No modal close/open cycle
+- Smooth form transition
+- Preserves any input data (if applicable)
+
+---
+
+### handleNavigateToLogin
+
+**Purpose**: Switch modal from register to login mode.
+
+**Rules**:
+- MUST change mode to `'login'`
+- MUST keep modal open
+- MUST update form display
+
+**Constraints**:
+- No modal close/open cycle
+- Smooth form transition
+- Clears register form data
+
+---
+
+### handleDismiss
+
+**Purpose**: Handle modal dismiss event (user swipes down or taps backdrop).
+
+**Rules**:
+- MUST reset modal state
+- MUST clear mode to default
+- MUST clear any pending callbacks
+- MUST handle cleanup
+
+**Constraints**:
+- Called by BottomSheetModal onDismiss
+- Auto-executed on user action
+- Cleanup required
+
+---
+
+### handleClose
+
+**Purpose**: Programmatically close modal and cleanup.
+
+**Rules**:
+- MUST close modal
+- MUST reset modal state
+- MUST clear pending callbacks
+- MUST execute cleanup
+
+**Constraints**:
+- Programmatic close
+- Same cleanup as dismiss
+- Safe to call multiple times
+
+---
+
+## Social Authentication
+
+### handleGoogleSignIn
+
+**Purpose**: Initiate Google OAuth flow from modal.
+
+**Rules**:
+- MUST call Google auth function
+- MUST handle loading state
+- MUST display errors to user
+- MUST auto-close modal on success
+
+**MUST NOT**:
+- Call if provider not configured
+- Leave loading state indefinitely
+- Ignore auth results
+
+**Constraints**:
+- Uses configured Google client IDs
+- Auto-closes on successful auth
+- Stays open on failure (for retry)
+- Loading state managed automatically
+
+---
+
+### handleAppleSignIn
+
+**Purpose**: Initiate Apple Sign-In flow from modal.
+
+**Rules**:
+- MUST call Apple auth function
+- MUST handle loading state
+- MUST display errors to user
+- MUST auto-close modal on success
+
+**MUST NOT**:
+- Call if provider not available
+- Call on non-iOS platforms
+- Leave loading state indefinitely
+
+**Constraints**:
+- iOS only (hidden on other platforms)
+- Requires Apple Developer account
+- Auto-closes on successful auth
+- Stays open on failure (for retry)
+
+---
+
+## Auto-Close Behavior
 
-### Auth Modal Tetikleme
+### Strategy
 
+**Purpose**: Automatically close modal after successful authentication.
+
+**Rules**:
+- MUST close modal on successful auth
+- MUST execute pending callback after close
+- MUST not close on auth failure
+- MUST not close if user cancels
+
+**MUST NOT**:
+- Stay open after successful auth
+- Close prematurely during auth flow
+- Execute callback before auth complete
+
+### Constraints
+
+**AUTO-CLOSE TRIGGERS**:
+- Anonymous → Authenticated: Close modal
+- Unauthenticated → Authenticated: Close modal
+- Authenticated → Authenticated (reauth): No close needed
+
+**PENDING CALLBACKS**:
+- Stored in authModalStore
+- Executed after successful auth
+- Cleared after execution
+- Can be action (navigate, API call, etc.)
+
+**NO-CLOSE SCENARIOS**:
+- Authentication failure
+- User cancellation
+- Network errors
+- Validation errors
+
+---
+
+## Pending Callbacks
+
+### Strategy
+
+**Purpose**: Execute callback after successful authentication.
+
+**Use Cases**:
+- Retry protected action after auth
+- Navigate to intended destination
+- Trigger post-auth operations
+- Restore user flow
+
+**Rules**:
+- MUST store callback before showing modal
+- MUST execute after successful auth
+- MUST clear after execution
+- MUST handle callback errors
+
+**MUST NOT**:
+- Execute callback before auth
+- Forget callback after auth
+- Execute multiple times
+- Lose callback context
+
+### Constraints
+
+**CALLBACK TYPES**:
+- Navigation function
+- Async operation
+- State update
+- Any void-returning function
+
+**EXECUTION TIMING**:
+- After successful authentication
+- Before modal close
+- Before UI updates
+- Can be async
+
+**ERROR HANDLING**:
+- Catch callback errors
+- Show error to user
+- Don't block auth completion
+- Log errors for debugging
+
+---
+
+## Configuration
+
+### Social Authentication Config
+
+**socialConfig** parameter structure:
+
+**GOOGLE CONFIG**:
 ```typescript
-function RequireAuthButton() {
-  const { showAuthModal } = useAuthModalStore();
-  const { isAuthenticated } = useAuth();
-
-  const handlePress = () => {
-    if (!isAuthenticated) {
-      // Login modal'ını göster
-      showAuthModal(undefined, 'login');
-      return;
-    }
-
-    // Auth gerektiren işlemi yap
-    console.log('İşlem başarılı');
-  };
-
-  return (
-    <Button onPress={handlePress}>
-      Auth Gerektiren İşlem
-    </Button>
-  );
+google?: {
+  iosClientId?: string;
+  webClientId?: string;
+  androidClientId?: string;
 }
 ```
+At least one client ID required
 
-### Pending Callback ile
-
+**APPLE CONFIG**:
 ```typescript
-function AddToFavoritesButton() {
-  const { showAuthModal } = useAuthModalStore();
-  const { isAuthenticated } = useAuth();
-
-  const handleAddToFavorites = async () => {
-    if (!isAuthenticated) {
-      // Authentication sonrası çalışacak callback'i kaydet
-      showAuthModal(async () => {
-        await addToFavorites(postId);
-        Alert.alert('Başarılı', 'Favorilere eklendi');
-      }, 'login');
-      return;
-    }
-
-    // Kullanıcı authenticated, doğrudan işlemi yap
-    await addToFavorites(postId);
-    Alert.alert('Başarılı', 'Favorilere eklendi');
-  };
-
-  return (
-    <Button onPress={handleAddToFavorites}>
-      Favorilere Ekle
-    </Button>
-  );
+apple?: {
+  enabled: boolean;
 }
 ```
 
-## Otomatik Kapanma
+**Rules**:
+- MUST provide client IDs for Google
+- MUST enable Apple explicitly if needed
+- MUST match Firebase console configuration
 
-Hook, başarılı authentication sonrası otomatik olarak modal'ı kapatır:
+**Constraints**:
+- Google: Requires at least one client ID
+- Apple: Only works on iOS
+- Both: Require Firebase setup
 
-- **Authenticated olmadan authenticated olmaya**: Kullanıcı giriş yaptığında
-- **Anonymous'den authenticated olmaya**: Anonymous kullanıcı kayıt olduğunda
+---
 
-```typescript
-// Kullanıcı giriş yapar
-// → useAuth store güncellenir
-// → useAuthBottomSheet bunu tespit eder
-// → Modal otomatik kapanır
-// → Pending callback çalıştırılır
-```
+## Loading States
 
-## Provider Kontrolü
+### Strategy
 
-Hook hangi provider'ların mevcut olduğunu otomatik belirler:
+**Purpose**: Proper loading indication during authentication.
 
-```typescript
-const { providers } = useAuthBottomSheet({
-  socialConfig: {
-    google: { webClientId: '...' },
-    apple: { enabled: true },
-  },
-});
-
-// iOS: ['apple', 'google'] veya ['google']
-// Android: ['google']
-// Web: ['google']
-```
+**Rules**:
+- MUST show loading during auth operation
+- MUST disable auth buttons during loading
+- MUST re-enable after completion
+- MUST handle concurrent operations
 
-## Hata Yönetimi
+**MUST NOT**:
+- Allow multiple concurrent auth operations
+- Leave loading state indefinitely
+- Allow button press during loading
 
-```typescript
-function AuthBottomSheetWithErrorHandling() {
-  const {
-    modalRef,
-    mode,
-    handleGoogleSignIn,
-    handleAppleSignIn,
-  } = useAuthBottomSheet({
-    socialConfig: {
-      google: { webClientId: Config.GOOGLE_WEB_CLIENT_ID },
-      apple: { enabled: true },
-    },
-  });
-
-  const handleGoogleSignInWithErrorHandling = async () => {
-    try {
-      await handleGoogleSignIn();
-      // Hook hata yönetimini içeride yapar
-    } catch (error) {
-      // Additional error handling if needed
-      Alert.alert('Hata', 'Bir sorun oluştu');
-    }
-  };
-
-  return (
-    <BottomSheetModal ref={modalRef}>
-      <Button onPress={handleGoogleSignInWithErrorHandling}>
-        Google ile Giriş
-      </Button>
-    </BottomSheetModal>
-  );
-}
-```
+### Constraints
+
+**LOADING STATES**:
+- `googleLoading: boolean` - Google auth in progress
+- `appleLoading: boolean` - Apple auth in progress
+
+**VISUAL FEEDBACK**:
+- Disable buttons during loading
+- Show spinner/indicator
+- Prevent mode switch during loading
+- Clear errors on new operation
+
+---
+
+## Error Handling
+
+### Strategy
+
+**Purpose**: Graceful error handling in modal context.
+
+**Rules**:
+- MUST display errors in modal
+- MUST keep modal open on error
+- MUST allow retry after error
+- MUST clear errors on new operation
+
+**MUST NOT**:
+- Close modal on error
+- Show raw error messages
+- Block retry indefinitely
+- Lose user context
+
+### Constraints
+
+**ERROR DISPLAY**:
+- In-modal error message
+- Clear retry option
+- User-friendly text
+- Localized messages
+
+**ERROR RECOVERY**:
+- User can retry same operation
+- Can switch to different provider
+- Can switch to login/register
+- Manual dismiss if desired
+
+---
+
+## Modal Lifecycle
+
+### Strategy
+
+**Purpose**: Proper modal lifecycle management.
+
+**OPENING**:
+1. Trigger: `showAuthModal` called
+2. Mode: Set to 'login' or 'register'
+3. Callback: Stored if provided
+4. Modal: Opens with animation
+
+**DURING AUTH**:
+1. User fills form or clicks social button
+2. Loading state shown
+3. Auth operation executed
+4. Success or failure determined
+
+**CLOSING**:
+1. Success: Auto-close + callback execution
+2. Failure: Stays open for retry
+3. Dismiss: Cleanup + reset
+4. Cancel: Cleanup + reset
+
+**Rules**:
+- MUST follow lifecycle sequence
+- MUST cleanup on every close
+- MUST reset state appropriately
+- MUST not leak memory
+
+---
+
+## Integration Points
+
+### Store Integration
+
+**authModalStore** manages:
+- Modal open/close state
+- Current mode (login/register)
+- Pending callback
+- Social auth configuration
+
+**Rules**:
+- MUST use store for modal state
+- MUST not duplicate state locally
+- MUST subscribe to store updates
+- MUST trigger store actions
+
+---
+
+## Related Hooks
+
+- **`useAuth`** (`src/presentation/hooks/useAuth.ts`) - Authentication state
+- **`useSocialLogin`** (`src/presentation/hooks/useSocialLogin.md`) - Social authentication
+- **`useAuthRequired`** (`src/presentation/hooks/useAuthRequired.md`) - Auth requirement checks
 
-## İlgili Component'ler
+## Related Components
 
-- [`AuthBottomSheet`](../components/AuthBottomSheet.md) - Bottom sheet component'i
-- [`useAuthModalStore`](../stores/authModalStore.md) - Auth modal state store'u
-- [`LoginForm`](../components/LoginForm.md) - Login form component'i
-- [`RegisterForm`](../components/RegisterForm.md) - Register form component'i
+- **`AuthBottomSheet`** (`src/presentation/components/AuthBottomSheet.tsx`) - Modal component
+- **`LoginForm`** (`src/presentation/components/LoginForm.md`) - Login form
+- **`RegisterForm`** (`src/presentation/components/LoginForm.md`) - Registration form
+- **`SocialLoginButtons`** (`src/presentation/components/SocialLoginButtons.md`) - Social auth UI
 
-## İlgili Hook'lar
+## Related Stores
 
-- [`useGoogleAuth`](./useSocialLogin.md#usegoogleauth) - Google auth hook'u
-- [`useAppleAuth`](./useSocialLogin.md#useappleauth) - Apple auth hook'u
-- [`useAuth`](./useAuth.md) - Ana auth state yönetimi
+- **`authModalStore`** (`src/presentation/stores/authModalStore.ts`) - Modal state management