@umituz/react-native-auth 3.4.31 → 3.4.33

package/src/presentation/components/ProfileComponents.md

@@ -1,432 +1,378 @@
 # Profile Components
 
-Kullanıcı profili ve hesap yönetimi için component'ler.
-
-## Component'ler
-
-- **[`ProfileSection`](#profilesection)** - Profil bölümü
-- **[`AccountActions`](#accountactions)** - Hesap işlemleri
+Components for displaying user profile information and managing account actions.
 
 ---
 
 ## ProfileSection
 
-Kullanıcı profil bilgilerini gösteren component. Avatar, isim ve kullanıcı ID'si içerir.
+Displays user profile information including avatar, name, and authentication status.
+
+### Strategy
 
-### Kullanım
+**Purpose**: Show user profile information with different layouts for authenticated vs anonymous users.
 
+**When to Use**:
+- Settings screens showing user info
+- Profile headers in navigation
+- Account management sections
+- User identification in UI
+
+**Import Path**:
 ```typescript
 import { ProfileSection } from '@umituz/react-native-auth';
-
-function SettingsScreen() {
-  const profile = useUserProfile({
-    accountRoute: 'AccountSettings',
-  });
-
-  const navigation = useNavigation();
-
-  return (
-    <View>
-      <ProfileSection
-        profile={{
-          displayName: profile?.displayName,
-          userId: profile?.userId,
-          isAnonymous: profile?.isAnonymous || false,
-          avatarUrl: profile?.avatarUrl,
-          accountSettingsRoute: profile?.accountSettingsRoute,
-        }}
-        onPress={() => navigation.navigate('EditProfile')}
-        onSignIn={() => navigation.navigate('Login')}
-        signInText="Giriş Yap"
-        anonymousText="Misafir"
-      />
-    </View>
-  );
-}
 ```
 
-### Props
+**Component Location**: `src/presentation/components/ProfileSection.tsx`
 
-| Prop | Tip | Required | Açıklama |
-|------|-----|----------|----------|
-| `profile` | `ProfileSectionConfig` | Yes | Profil konfigürasyonu |
-| `onPress` | `() => void` | No | Press handler (authenticated kullanıcılar için) |
-| `onSignIn` | `() => void` | No | Sign-in handler (anonymous kullanıcılar için) |
-| `signInText` | `string` | No | "Giriş Yap" metni |
-| `anonymousText` | `string` | No | Anonymous kullanıcı metni |
+**Data Hook**: `src/presentation/hooks/useUserProfile.ts`
 
-#### ProfileSectionConfig
+### Rules
 
-```typescript
-interface ProfileSectionConfig {
-  displayName?: string;        // Görünen ad
-  userId?: string;             // Kullanıcı ID'si
-  isAnonymous: boolean;        // Anonymous mu
-  avatarUrl?: string;          // Profil fotoğrafı URL'si
-  accountSettingsRoute?: string; // Hesap ayarları route'u
-  benefits?: string[];         // Faydalar listesi
-}
-```
+**MUST**:
+- Pass profile object with required fields
+- Provide different handlers for authenticated vs anonymous users
+- Show avatar fallback if no photo available
+- Display authentication status clearly
+- Handle navigation to profile editing
 
-### Örnekler
+**MUST NOT**:
+- Show sensitive information (user ID, email publicly)
+- Allow anonymous users to access profile editing
+- Display generic avatar for authenticated users without photo
+- Hardcode profile data (use useUserProfile hook)
 
-#### Authenticated Kullanıcı
+### Constraints
 
-```typescript
-function ProfileSection() {
-  const { user } = useAuth();
-
-  const profile = {
-    displayName: user?.displayName || user?.email,
-    userId: user?.uid,
-    isAnonymous: false,
-    avatarUrl: user?.photoURL,
-    accountSettingsRoute: 'AccountSettings',
-  };
-
-  const navigation = useNavigation();
-
-  return (
-    <ProfileSection
-      profile={profile}
-      onPress={() => navigation.navigate('EditProfile')}
-    />
-  );
-}
-```
+**AUTHENTICATED USER DISPLAY**:
+- Show display name or email
+- Show avatar if available
+- Show "Edit Profile" or settings access
+- Hide authentication prompts
 
-#### Anonymous Kullanıcı
+**ANONYMOUS USER DISPLAY**:
+- Show "Guest" or anonymous label
+- Show generic placeholder avatar
+- Show "Sign In" or "Create Account" prompt
+- Hide profile editing options
 
+**REQUIRED PROPERTIES**:
 ```typescript
-function ProfileSection() {
-  const { user } = useAuth();
-
-  const profile = {
-    displayName: 'Misafir Kullanıcı',
-    userId: undefined,
-    isAnonymous: true,
-    avatarUrl: undefined,
-  };
-
-  const navigation = useNavigation();
-
-  return (
-    <ProfileSection
-      profile={profile}
-      onSignIn={() => navigation.navigate('Login')}
-      signInText="Giriş Yap"
-    />
-  );
+{
+  displayName?: string;
+  isAnonymous: boolean;
+  avatarUrl?: string;
+  accountSettingsRoute?: string;
 }
 ```
 
-#### Benefits ile
+**PLATFORM SUPPORT**:
+- iOS: ✅ Fully supported
+- Android: ✅ Fully supported
+- Web: ✅ Fully supported
 
-```typescript
-function PremiumProfileSection() {
-  const { user } = useAuth();
-
-  const profile = {
-    displayName: user?.displayName,
-    userId: user?.uid,
-    isAnonymous: false,
-    avatarUrl: user?.photoURL,
-    benefits: [
-      'Premium içeriklere erişim',
-      'Reklamsız deneyim',
-      'Özel indirimler',
-    ],
-  };
-
-  return <ProfileSection profile={profile} />;
-}
-```
+---
+
+## AccountActions
 
-#### Dynamic Profile
+Provides buttons for account management operations like sign out and account deletion.
 
+### Strategy
+
+**Purpose**: Safe account management with proper confirmations and error handling.
+
+**When to Use**:
+- Account settings screens
+- Logout functionality
+- Account deletion flows
+- Password change access
+
+**Import Path**:
 ```typescript
-function DynamicProfileSection() {
-  const { user } = useAuth();
-  const navigation = useNavigation();
-  const profile = useUserProfile();
-
-  const handlePress = () => {
-    if (profile?.isAnonymous) {
-      navigation.navigate('Login');
-    } else {
-      navigation.navigate('EditProfile');
-    }
-  };
-
-  return (
-    <ProfileSection
-      profile={{
-        displayName: profile?.displayName,
-        userId: profile?.userId,
-        isAnonymous: profile?.isAnonymous || false,
-        avatarUrl: profile?.avatarUrl,
-        benefits: profile?.isAnonymous
-          ? ['Hesap oluşturarak daha fazla özelliğe erişin']
-          : ['Premium üyelik alın', 'Ayrıcalıklı içeriklere erişin'],
-      }}
-      onPress={handlePress}
-    />
-  );
-}
+import { AccountActions } from '@umituz/react-native-auth';
 ```
 
+**Component Location**: `src/presentation/components/AccountActions.tsx`
+
+**Management Hook**: `src/presentation/hooks/useAccountManagement.ts`
+
+### Rules
+
+**MUST**:
+- Require confirmation before sign out
+- Require confirmation before account deletion
+- Show clear warnings for account deletion
+- Provide error messages for failures
+- Handle loading states during operations
+- Hide deletion option for anonymous users
+
+**MUST NOT**:
+- Allow account deletion without confirmation
+- Delete account without recent authentication
+- Show account actions to anonymous users
+- Allow immediate destructive actions
+- Expose internal error messages
+
+### Constraints
+
+**SIGN OUT REQUIREMENTS**:
+- Confirmation dialog required
+- Clear sign-out message
+- Cancel option must be available
+- Non-destructive (can sign back in)
+
+**ACCOUNT DELETION REQUIREMENTS**:
+- Double confirmation required (warning + confirm)
+- Clear warning about irreversibility
+- Recent authentication required (Firebase requirement)
+- Error handling for re-authentication failures
+- Cannot delete anonymous accounts
+
+**PASSWORD CHANGE**:
+- Optional feature (configurable)
+- Only for email/password users
+- Requires current password
+- Not available for social auth users
+
+**OPERATION SAFETY**:
+- Disable buttons during operation
+- Show loading indicators
+- Prevent concurrent operations
+- Allow retry on failure
+- Log security events
+
 ---
 
-## AccountActions
+## Anonymous User Handling
 
-Hesap yönetimi işlemlerini içeren component. Çıkış yapma, şifre değiştirme ve hesap silme butonlarını sağlar.
+### Strategy
 
-### Kullanım
+**Purpose**: Differentiate experience between authenticated and anonymous users appropriately.
 
-```typescript
-import { AccountActions } from '@umituz/react-native-auth';
+### Rules
 
-function AccountSettingsScreen() {
-  const { logout, deleteAccount } = useAccountManagement();
-  const navigation = useNavigation();
-
-  const config = {
-    logoutText: 'Çıkış Yap',
-    deleteAccountText: 'Hesabı Sil',
-    changePasswordText: 'Şifre Değiştir',
-    logoutConfirmTitle: 'Çıkış Yap',
-    logoutConfirmMessage: 'Çıkış yapmak istediğinizden emin misiniz?',
-    deleteConfirmTitle: 'Hesabı Sil',
-    deleteConfirmMessage: 'Bu işlem geri alınamaz. Devam etmek istiyor musunuz?',
-    deleteErrorTitle: 'Hata',
-    deleteErrorMessage: 'Hesap silinemedi. Lütfen tekrar deneyin.',
-    onLogout: async () => {
-      await logout();
-      navigation.replace('Login');
-    },
-    onDeleteAccount: async () => {
-      await deleteAccount();
-      navigation.replace('Login');
-    },
-    showChangePassword: true,
-    onChangePassword: () => {
-      navigation.navigate('ChangePassword');
-    },
-  };
-
-  return (
-    <View>
-      <AccountActions config={config} />
-    </View>
-  );
-}
-```
+**MUST**:
+- Hide account deletion for anonymous users
+- Show "Create Account" prompt instead of sign out
+- Indicate guest status clearly
+- Guide anonymous users toward registration
 
-### Props
+**MUST NOT**:
+- Show account deletion to anonymous users
+- Allow sign out of anonymous session (unless upgrading)
+- Treat anonymous users as authenticated
+- Hide anonymous status from user
 
-| Prop | Tip | Required | Açıklama |
-|------|-----|----------|----------|
-| `config` | `AccountActionsConfig` | Yes | Hesap işlemleri konfigürasyonu |
+### Constraints
 
-#### AccountActionsConfig
+**ANONYMOUS USER LIMITATIONS**:
+- Cannot delete anonymous account
+- Cannot change password (no password set)
+- Cannot access profile editing
+- Limited account settings access
 
-```typescript
-interface AccountActionsConfig {
-  logoutText: string;                  // "Çıkış Yap" butonu metni
-  deleteAccountText: string;           // "Hesabı Sil" butonu metni
-  changePasswordText?: string;         // "Şifre Değiştir" butonu metni
-  logoutConfirmTitle: string;          // Çıkış onay başlığı
-  logoutConfirmMessage: string;        // Çıkış onay mesajı
-  deleteConfirmTitle: string;          // Silme onay başlığı
-  deleteConfirmMessage: string;        // Silme onay mesajı
-  deleteErrorTitle?: string;           // Silme hata başlığı
-  deleteErrorMessage?: string;         // Silme hata mesajı
-  onLogout: () => Promise<void>;       // Çıkış handler
-  onDeleteAccount: () => Promise<void>; // Silme handler
-  onChangePassword?: () => void;       // Şifre değiştirme handler
-  showChangePassword?: boolean;        // Şifre değiştirme butonu göster
-}
-```
+**UPGRADE PATH**:
+- Anonymous → Registered: Link credentials
+- Preserves anonymous account data
+- Requires email/password or social auth
+- Seamless transition for user
 
-### Örnekler
+---
 
-#### Basit Kullanım
+## Security & Privacy
 
-```typescript
-function SimpleAccountActions() {
-  const { logout, deleteAccount } = useAccountManagement();
-
-  const config = {
-    logoutText: 'Çıkış Yap',
-    deleteAccountText: 'Hesabı Sil',
-    logoutConfirmTitle: 'Çıkış Yap',
-    logoutConfirmMessage: 'Çıkış yapmak istiyor musunuz?',
-    deleteConfirmTitle: 'Hesabı Sil',
-    deleteConfirmMessage: 'Hesabınızı silmek istediğinizden emin misiniz?',
-    onLogout: logout,
-    onDeleteAccount: deleteAccount,
-  };
-
-  return <AccountActions config={config} />;
-}
-```
+### Strategy
 
-#### Şifre Değiştirme ile
+**Purpose**: Protect user information and prevent unauthorized account access.
 
-```typescript
-function AccountActionsWithPasswordChange() {
-  const { logout, deleteAccount } = useAccountManagement();
-  const navigation = useNavigation();
-
-  const config = {
-    logoutText: 'Çıkış Yap',
-    deleteAccountText: 'Hesabı Sil',
-    changePasswordText: 'Şifre Değiştir',
-    logoutConfirmTitle: 'Çıkış Yap',
-    logoutConfirmMessage: 'Çıkış yapmak istiyor musunuz?',
-    deleteConfirmTitle: 'Hesabı Sil',
-    deleteConfirmMessage: 'Hesabınızı silmek istediğinizden emin misiniz?',
-    onLogout: async () => {
-      await logout();
-      navigation.replace('Login');
-    },
-    onDeleteAccount: async () => {
-      await deleteAccount();
-      navigation.replace('Login');
-    },
-    showChangePassword: true,
-    onChangePassword: () => {
-      navigation.navigate('ChangePassword');
-    },
-  };
-
-  return <AccountActions config={config} />;
-}
-```
+### Rules
 
-#### Custom Error Handling
+**MUST**:
+- Never display full user ID in UI
+- Never expose sensitive tokens
+- Require recent auth for destructive actions
+- Log account management events
+- Validate permissions before actions
 
-```typescript
-function AccountActionsWithErrorHandling() {
-  const { logout, deleteAccount } = useAccountManagement();
-  const navigation = useNavigation();
-
-  const config = {
-    logoutText: 'Çıkış Yap',
-    deleteAccountText: 'Hesabı Sil',
-    logoutConfirmTitle: 'Çıkış Yap',
-    logoutConfirmMessage: 'Çıkış yapmak istiyor musunuz?',
-    deleteConfirmTitle: 'Hesabı Sil',
-    deleteConfirmMessage: 'Bu işlem geri alınamaz. Emin misiniz?',
-    deleteErrorTitle: 'Hesap Silinemedi',
-    deleteErrorMessage: 'Hesabınız silinirken bir hata oluştu. Lütfen daha sonra tekrar deneyin veya destek ile iletişime geçin.',
-    onLogout: async () => {
-      try {
-        await logout();
-        navigation.replace('Login');
-      } catch (error) {
-        Alert.alert('Hata', 'Çıkış yapılamadı');
-      }
-    },
-    onDeleteAccount: async () => {
-      try {
-        await deleteAccount();
-        Alert.alert('Başarılı', 'Hesabınız silindi');
-        navigation.replace('Login');
-      } catch (error) {
-        // Hata otomatik olarak gösterilir (deleteErrorMessage)
-        throw error;
-      }
-    },
-  };
-
-  return <AccountActions config={config} />;
-}
-```
+**MUST NOT**:
+- Show user ID or internal identifiers
+- Display raw email publicly
+- Allow account deletion without re-auth
+- Skip confirmation dialogs
+- Log sensitive data
 
-#### Anonymous Kullanıcı İçin
+### Constraints
 
-```typescript
-function AccountActionsAnonymous() {
-  const { isAnonymous } = useAuth();
-
-  if (isAnonymous) {
-    return (
-      <Button onPress={() => navigation.navigate('Register')}>
-        Hesap Oluştur
-      </Button>
-    );
-  }
-
-  const config = {
-    logoutText: 'Çıkış Yap',
-    deleteAccountText: 'Hesabı Sil',
-    logoutConfirmTitle: 'Çıkış Yap',
-    logoutConfirmMessage: 'Çıkış yapmak istiyor musunuz?',
-    deleteConfirmTitle: 'Hesabı Sil',
-    deleteConfirmMessage: 'Hesabınızı silmek istediğinizden emin misiniz?',
-    onLogout: logout,
-    onDeleteAccount: deleteAccount,
-  };
-
-  return <AccountActions config={config} />;
-}
-```
+**INFORMATION DISPLAY**:
+- Display name: OK
+- Email: Only to account owner
+- User ID: Never in UI
+- Auth tokens: Never in logs
 
-## Birlikte Kullanım
+**RE-AUTHENTICATION**:
+- Required for: Account deletion, password change
+- Timeout: Usually 5 minutes in Firebase
+- Methods: Re-sign in with existing credentials
+- Failure: Block destructive action
 
-```typescript
-function AccountSettingsScreen() {
-  const profile = useUserProfile();
-  const { logout, deleteAccount } = useAccountManagement();
-  const navigation = useNavigation();
-
-  return (
-    <ScrollView>
-      {/* Profil bölümü */}
-      <ProfileSection
-        profile={{
-          displayName: profile?.displayName,
-          userId: profile?.userId,
-          isAnonymous: profile?.isAnonymous || false,
-          avatarUrl: profile?.avatarUrl,
-        }}
-        onPress={() => navigation.navigate('EditProfile')}
-      />
-
-      {/* Hesap işlemleri */}
-      {!profile?.isAnonymous && (
-        <AccountActions
-          config={{
-            logoutText: 'Çıkış Yap',
-            deleteAccountText: 'Hesabı Sil',
-            logoutConfirmTitle: 'Çıkış Yap',
-            logoutConfirmMessage: 'Çıkış yapmak istiyor musunuz?',
-            deleteConfirmTitle: 'Hesabı Sil',
-            deleteConfirmMessage: 'Bu işlem geri alınamaz. Emin misiniz?',
-            onLogout: async () => {
-              await logout();
-              navigation.replace('Login');
-            },
-            onDeleteAccount: async () => {
-              await deleteAccount();
-              navigation.replace('Login');
-            },
-          }}
-        />
-      )}
-    </ScrollView>
-  );
-}
-```
+**EVENT LOGGING**:
+- Log: Account views, settings access
+- Log: Sign out, deletion attempts
+- Never log: Passwords, tokens, full emails
+- Purpose: Security audit, debugging
+
+---
+
+## Navigation Integration
+
+### Strategy
+
+**Purpose**: Proper navigation flow for profile-related screens.
+
+### Rules
+
+**MUST**:
+- Provide navigation callbacks for all actions
+- Handle back navigation properly
+- Pass profile data to edit screens
+- Return to proper screen after actions
+
+**MUST NOT**:
+- Hardcode navigation paths
+- Break back navigation stack
+- Lose unsaved changes
+- Leave modals open after actions
+
+### Constraints
+
+**NAVIGATION FLOWS**:
+- Profile → Edit Profile → Back to Profile
+- Profile → Account Settings → Back to Profile
+- Sign Out → Login Screen (replace stack)
+- Delete Account → Welcome/Login (replace stack)
+
+**STACK MANAGEMENT**:
+- Sign out: Replace entire stack
+- Delete account: Replace entire stack
+- Edit profile: Push onto stack
+- Settings: Push onto stack
+
+---
+
+## Error Handling
+
+### Strategy
+
+**Purpose**: Clear user feedback for account action failures.
+
+### Rules
+
+**MUST**:
+- Show user-friendly error messages
+- Provide retry options after failures
+- Distinguish error types clearly
+- Guide users to resolution
+- Log errors for debugging
+
+**MUST NOT**:
+- Show raw error codes to users
+- Expose technical details
+- Block retry indefinitely
+- Crash on errors
+
+### Constraints
+
+**ERROR CATEGORIES**:
+- Network errors: "Check your connection"
+- Re-auth required: "Please sign in again"
+- Permission denied: "You don't have permission"
+- Rate limited: "Please try again later"
 
-## İlgili Component'ler
+**RECOVERY OPTIONS**:
+- Retry button for temporary failures
+- Sign-in prompt for re-auth
+- Support contact for persistent issues
+- Graceful degradation
 
-- [`EditProfileForm`](./EditProfileForm.md) - Profil düzenleme formu
-- [`EditProfileAvatar`](./EditProfileAvatar.md) - Profil fotoğrafı düzenleme
+---
+
+## Design System Integration
+
+### Strategy
+
+**Purpose**: Consistent styling with application design system.
+
+### Rules
+
+**MUST**:
+- Use design system color tokens
+- Follow design system spacing
+- Use design system typography
+- Match design system component styles
+- Respect design system dark mode
+
+**MUST NOT**:
+- Hardcode colors or sizes
+- Use custom styles outside system
+- Break responsive layouts
+- Ignore accessibility tokens
+
+### Constraints
+
+**STYLE TOKENS**:
+- Colors: Primary, danger, background, text
+- Spacing: Consistent gaps and padding
+- Typography: System fonts and sizes
+- Icons: Design system icon set
+- Avatar sizes: Defined in system
+
+**DARK MODE**:
+- Automatically support dark mode
+- Use system color tokens
+- Test contrast in both modes
+- No hardcoded colors
+
+---
+
+## Accessibility Requirements
+
+### Strategy
+
+**Purpose**: Ensure profile components are accessible to all users.
+
+### Rules
+
+**MUST**:
+- Provide accessibility labels for buttons
+- Announce state changes to screen readers
+- Support keyboard navigation (web)
+- Maintain proper focus order
+- Use semantic HTML elements (web)
+
+**MUST NOT**:
+- Rely on color alone for meaning
+- Hide important information from screen readers
+- Break keyboard navigation
+- Use low contrast colors
+
+### Constraints
+
+**SCREEN READER**:
+- Announce user name and status
+- Announce button actions clearly
+- Provide hints for destructive actions
+- Announce loading states
+
+**VISUAL ACCESSIBILITY**:
+- Minimum contrast: 4.5:1 for text
+- Touch targets: 44x44px minimum
+- Clear focus indicators
+- Not color-dependent
+
+---
 
-## İlgili Hook'lar
+## Related Hooks
 
-- [`useUserProfile`](../hooks/useUserProfile.md) - Profil verileri hook'u
-- [`useAccountManagement`](../hooks/useAccountManagement.md) - Hesap yönetimi hook'u
-- [`useAuth`](../hooks/useAuth.md) - Ana auth state yönetimi
+- **`useUserProfile`** (`src/presentation/hooks/useUserProfile.ts`) - Profile data management
+- **`useAccountManagement`** (`src/presentation/hooks/useAccountManagement.ts`) - Account operations
+- **`useAuth`** (`src/presentation/hooks/useAuth.ts`) - Authentication state