@umituz/react-native-design-system 2.6.94 → 2.6.96

package/src/molecules/alerts/README.md

@@ -1,471 +1,388 @@
 # Alert System
 
-React Native Design System, farklı durumlarda kullanılmak üzere kapsamlı bir alert sistemi sunar. Her alert türü farklı kullanım senaryoları için optimize edilmiştir.
+React Native Design System provides a comprehensive alert system for different use cases. Each alert type is optimized for specific scenarios.
 
-## Alert Türleri
+## Import & Usage
 
-- **AlertBanner** - Sayfanın üstünde kalıcı uyarı
-- **AlertToast** - Geçici bildirim mesajları
-- **AlertInline** - Form içinde satır içi uyarı
-- **AlertModal** - Modal onay dialog'u
-- **AlertContainer** - Alert yönetim container'ı
-
-## Kurulum
-
-```tsx
+```typescript
 import {
   AlertBanner,
   AlertToast,
   AlertInline,
   AlertModal,
-  AlertContainer
-} from 'react-native-design-system';
+  AlertContainer,
+  useAlert
+} from 'react-native-design-system/src/molecules/alerts';
 ```
 
-## AlertBanner
+**Location:** `src/molecules/alerts/`
 
-Sayfa üstünde kalıcı uyarı göstermek için kullanılır.
-
-### Temel Kullanım
+## Basic Usage
 
 ```tsx
-<AlertBanner
-  variant="info"
-  title="Bilgilendirme"
-  message="Bu özellik yakında kullanıma sunulacak"
-/>
-```
+import { useAlert } from 'react-native-design-system/src/molecules/alerts';
 
-### Variant'lar
+const { showToast } = useAlert();
 
-```tsx
-<View style={{ gap: 8 }}>
-  <AlertBanner variant="info" title="Bilgi" message="Bilgilendirme mesajı" />
-  <AlertBanner variant="success" title="Başarılı" message="İşlem başarılı" />
-  <AlertBanner variant="warning" title="Uyarı" message="Dikkat edilmesi gereken durum" />
-  <AlertBanner variant="error" title="Hata" message="Bir hata oluştu" />
-</View>
+showToast({
+  variant: 'success',
+  title: 'Success',
+  message: 'Operation completed',
+});
 ```
 
-### Kapatılabilir
+## Strategy
 
-```tsx
-<AlertBanner
-  variant="info"
-  title="Güncelleme Mevcut"
-  message="Yeni bir sürüm mevcut"
-  dismissible
-  onDismiss={() => console.log('Kapatıldı')}
-/>
-```
+**Purpose**: Provide consistent, accessible, and user-friendly alert mechanisms for different communication needs.
 
-### Action Button
+**When to Use**:
+- **AlertBanner**: Page-level notifications (maintenance, updates)
+- **AlertToast**: Temporary feedback (success, error messages)
+- **AlertInline**: Form validation errors
+- **AlertModal**: Critical confirmations (delete, irreversible actions)
 
-```tsx
-<AlertBanner
-  variant="warning"
-  title="Oturum Sona Erecek"
-  message="Oturumunuz 5 dakika içinde sona erecek"
-  actionLabel="Uzat"
-  onAction={() => console.log('Uzatıldı')}
-/>
-```
+**When NOT to Use**:
+- For navigation - use navigation components
+- For complex dialogs - use custom modals
+- For persistent content - use other UI patterns
 
-## AlertToast
+## Rules
 
-Geçici bildirimler için kullanılır. Otomatik olarak kapanır.
+### Required
 
-### Temel Kullanım
+1. **ALWAYS** wrap app in `AlertContainer` provider
+2. **MUST** use appropriate alert type for context
+3. **NEVER** show multiple alerts simultaneously
+4. **ALWAYS** provide meaningful messages
+5. **MUST** use i18n for user-facing text
 
-```tsx
-import { useAlert } from 'react-native-design-system';
+### Alert Types
 
-export const MyComponent = () => {
-  const { showToast } = useAlert();
+1. **AlertBanner**: Persistent page-level warnings
+2. **AlertToast**: Temporary notifications (auto-dismiss)
+3. **AlertInline**: Contextual form errors
+4. **AlertModal**: Critical confirmations (user action)
 
-  const handleSuccess = () => {
-    showToast({
-      variant: 'success',
-      title: 'Başarılı',
-      message: 'İşlem tamamlandı',
-    });
-  };
+### Variants
 
-  return (
-    <Button title="Gönder" onPress={handleSuccess} />
-  );
-};
-```
+1. **info**: Neutral information
+2. **success**: Successful operations
+3. **warning**: Warnings and cautions
+4. **error**: Errors and failures
+
+## Forbidden
 
-### Variant'lar
+❌ **NEVER** do these:
 
 ```tsx
-// Success
-showToast({
+// ❌ Missing provider
+export const App = () => {
+  return <MyApp />; // Missing AlertContainer ❌
+};
+
+// ❌ Wrong alert type
+useAlert().showAlert({
   variant: 'success',
-  title: 'Kaydedildi',
-  message: 'Değişiklikleriniz kaydedildi',
-});
+  message: 'Saved successfully',
+}); // Should be showToast ❌
+
+// ❌ Too many alerts
+const handleClick = () => {
+  showToast({ message: 'First' });
+  showToast({ message: 'Second' }); // ❌ Too many
+  showToast({ message: 'Third' });
+};
 
-// Error
+// ❌ Hardcoded text
 showToast({
-  variant: 'error',
-  title: 'Hata',
-  message: 'İşlem başarısız',
+  message: 'Success', // ❌ Use i18n
 });
 
-// Info
-showToast({
-  variant: 'info',
-  title: 'Bilgi',
-  message: 'Yeni özellik eklendi',
+// ❌ No variant
+showAlert({
+  message: 'Are you sure?',
+  // Missing variant ❌
 });
 
-// Warning
-showToast({
-  variant: 'warning',
-  title: 'Uyarı',
-  message: 'Lütfen kontrol edin',
+// ❌ Alert for navigation
+showAlert({
+  message: 'Go to settings',
+  onConfirm: () => navigate('Settings'), // ❌ Use navigation
 });
-```
-
-### Custom Süre
 
-```tsx
+// ❌ Too long messages
 showToast({
-  variant: 'info',
-  title: 'Mesaj',
-  message: '5 saniye gösterilecek',
-  duration: 5000,
+  message: 'This is an extremely long message that will be difficult to read and understand', // ❌
 });
 ```
 
-## AlertInline
+## Best Practices
 
-Form içinde satır içi uyarı için kullanılır.
+### Alert Type Selection
 
-### Temel Kullanım
+✅ **DO**:
+- Use AlertBanner for system-wide notices
+- Use AlertToast for quick feedback (3-5 seconds)
+- Use AlertInline for form validation
+- Use AlertModal for destructive actions
 
-```tsx
-<AlertInline
-  variant="error"
-  message="Bu alan zorunludur"
-/>
-```
+❌ **DON'T**:
+- Use AlertModal for simple notifications
+- Use AlertToast for critical confirmations
+- Use AlertBanner for temporary messages
+- Show multiple alerts at once
 
-### Form ile
+### Message Length
 
+✅ **DO**:
 ```tsx
-<View>
-  <FormField
-    label="E-posta"
-    value={email}
-    onChangeText={setEmail}
-    error={emailError}
-  />
+// Short for toast
+showToast({
+  message: 'Saved successfully', // Short and clear
+});
 
-  {emailError && (
-    <AlertInline
-      variant="error"
-      message="Geçerli bir e-posta adresi girin"
-    />
-  )}
-</View>
+// Detailed for modal
+showAlert({
+  title: 'Delete Item',
+  message: 'This action cannot be undone. Are you sure you want to continue?',
+  onConfirm: handleDelete,
+});
 ```
 
-## AlertModal
-
-Kritik onay dialog'ları için kullanılır.
+❌ **DON'T**:
+```tsx
+// Long toast message
+showToast({
+  message: 'Your changes have been saved successfully and you can continue with your work', // ❌ Too long
+});
+```
 
-### Temel Kullanım
+### Variant Usage
 
+✅ **DO**:
 ```tsx
-import { useAlert } from 'react-native-design-system';
+// Success - completed actions
+showToast({ variant: 'success', message: 'Saved' });
 
-export const DeleteConfirmation = () => {
-  const { showAlert } = useAlert();
+// Error - failed operations
+showToast({ variant: 'error', message: 'Failed to save' });
 
-  const handleDelete = () => {
-    showAlert({
-      variant: 'error',
-      title: 'Öğeyi Sil',
-      message: 'Bu öğeyi silmek istediğinizden emin misiniz? Bu işlem geri alınamaz.',
-      confirmLabel: 'Sil',
-      cancelLabel: 'İptal',
-      onConfirm: () => {
-        // Silme işlemi
-      },
-    });
-  };
+// Warning - potential issues
+showAlert({ variant: 'warning', message: 'Unsaved changes' });
 
-  return (
-    <Button title="Sil" onPress={handleDelete} />
-  );
-};
+// Info - neutral information
+showBanner({ variant: 'info', message: 'New feature available' });
 ```
 
-### Variant'lar
-
+❌ **DON'T**:
 ```tsx
-// Error
-showAlert({
-  variant: 'error',
-  title: 'Emin misiniz?',
-  message: 'Bu işlem geri alınamaz',
-  onConfirm: handleConfirm,
-});
-
-// Warning
-showAlert({
-  variant: 'warning',
-  title: 'Uyarı',
-  message: 'Devam etmek istiyor musunuz?',
-  onConfirm: handleConfirm,
-});
-
-// Info
-showAlert({
-  variant: 'info',
-  title: 'Bilgi',
-  message='Detaylı bilgi',
-  onConfirm: handleConfirm,
-});
+// Wrong variant for context
+showToast({ variant: 'error', message: 'Success!' }); // ❌ Wrong variant
 ```
 
-## AlertContainer
+## AI Coding Guidelines
 
-Alert sistemini yönetmek için kullanılır.
+### For AI Agents
 
-### Provider
+When generating Alert components, follow these rules:
 
-```tsx
-import { AlertContainer } from 'react-native-design-system';
+1. **Always import from correct path**:
+   ```typescript
+   import { useAlert } from 'react-native-design-system/src/molecules/alerts';
+   ```
 
-export const App = () => {
-  return (
-    <AlertContainer>
-      <MyApp />
-    </AlertContainer>
-  );
-};
-```
+2. **Always use appropriate alert type**:
+   ```tsx
+   // Quick feedback
+   const { showToast } = useAlert();
+   showToast({ variant: 'success', message: 'Saved' });
 
-### Hook Kullanımı
+   // Critical action
+   const { showAlert } = useAlert();
+   showAlert({ variant: 'error', onConfirm: delete });
 
-```tsx
-import { useAlert } from 'react-native-design-system';
+   // Form error
+   <AlertInline variant="error" message="Invalid input" />
 
-export const MyComponent = () => {
-  const { showToast, showAlert, showBanner } = useAlert();
+   // Page notice
+   <AlertBanner variant="warning" message="Maintenance mode" />
+   ```
 
-  // Toast göster
-  const handleSuccess = () => {
-    showToast({
-      variant: 'success',
-      title: 'Başarılı',
-      message: 'İşlem tamamlandı',
-    });
-  };
-
-  // Alert göster
-  const handleConfirm = () => {
-    showAlert({
-      variant: 'warning',
-      title: 'Onay',
-      message: 'Emin misiniz?',
-      onConfirm: () => console.log('Onaylandı'),
-    });
-  };
-
-  return (
-    <View>
-      <Button title="Başarılı" onPress={handleSuccess} />
-      <Button title="Onay" onPress={handleConfirm} />
-    </View>
-  );
-};
-```
-
-## Örnek Kullanımlar
-
-### Form Hataları
-
-```tsx
-export const LoginForm = () => {
-  const { showToast } = useAlert();
+3. **Always use i18n for messages**:
+   ```tsx
+   // ❌ Bad
+   showToast({ message: 'Success' });
 
-  const handleSubmit = () => {
-    if (!email) {
-      showToast({
-        variant: 'error',
-        title: 'Hata',
-        message: 'E-posta alanı zorunludur',
-      });
-      return;
-    }
+   // ✅ Good
+   showToast({ message: t('alerts.success') });
+   ```
 
-    // Form submit
-  };
-};
-```
+4. **Always provide variant**:
+   ```tsx
+   // ❌ Bad
+   showToast({ message: 'Something happened' });
 
-### API Hataları
+   // ✅ Good
+   showToast({ variant: 'info', message: t('alerts.info') });
+   ```
 
-```tsx
-export const DataLoader = () => {
-  const { showToast } = useAlert();
+5. **Never show multiple alerts**:
+   ```tsx
+   // ❌ Bad
+   const handleClick = () => {
+     showToast({ message: 'First' });
+     showToast({ message: 'Second' }); // Don't stack
+   };
 
-  const loadData = async () => {
-    try {
-      const data = await fetchData();
-      showToast({
-        variant: 'success',
-        title: 'Başarılı',
-        message: 'Veriler yüklendi',
-      });
-    } catch (error) {
-      showToast({
-        variant: 'error',
-        title: 'Hata',
-        message: 'Veriler yüklenemedi',
-      });
-    }
-  };
-};
-```
+   // ✅ Good
+   const handleClick = () => {
+     showToast({ message: 'Complete action' });
+   };
+   ```
 
-### Başarı Bildirimi
+### Common Patterns
 
+#### Success Feedback
 ```tsx
-export const SaveButton = () => {
-  const { showToast } = useAlert();
-
-  const handleSave = async () => {
+const handleSave = async () => {
+  try {
     await saveData();
     showToast({
       variant: 'success',
-      title: 'Kaydedildi',
-      message: 'Değişiklikleriniz başarıyla kaydedildi',
+      title: t('alerts.success'),
+      message: t('alerts.saved'),
     });
-  };
-};
-```
-
-### Silme Onayı
-
-```tsx
-export const DeleteButton = ({ itemId }) => {
-  const { showAlert } = useAlert();
-
-  const handleDelete = () => {
-    showAlert({
+  } catch (error) {
+    showToast({
       variant: 'error',
-      title: 'Öğeyi Sil',
-      message: 'Bu öğeyi silmek istediğinizden emin misiniz?',
-      confirmLabel: 'Sil',
-      cancelLabel: 'İptal',
-      onConfirm: async () => {
-        await deleteItem(itemId);
-        showToast({
-          variant: 'success',
-          title: 'Silindi',
-          message: 'Öğe başarıyla silindi',
-        });
-      },
+      title: t('alerts.error'),
+      message: t('alerts.saveFailed'),
     });
-  };
-
-  return (
-    <Button title="Sil" onPress={handleDelete} />
-  );
+  }
 };
 ```
 
-### Banner Uyarısı
-
+#### Delete Confirmation
 ```tsx
-export const MaintenanceBanner = () => {
-  return (
-    <AlertBanner
-      variant="warning"
-      title="Bakım Modu"
-      message="Sistem bakımda, bazı özellikler kullanılamayabilir"
-      dismissible
-    />
-  );
+const handleDelete = () => {
+  showAlert({
+    variant: 'error',
+    title: t('alerts.deleteTitle'),
+    message: t('alerts.deleteConfirm'),
+    confirmLabel: t('common.delete'),
+    cancelLabel: t('common.cancel'),
+    onConfirm: async () => {
+      await deleteItem();
+      showToast({
+        variant: 'success',
+        message: t('alerts.deleted'),
+      });
+    },
+  });
 };
 ```
 
-## Best Practices
+#### Form Validation
+```tsx
+<View>
+  <FormField
+    label="Email"
+    value={email}
+    onChangeText={setEmail}
+    error={emailError}
+  />
 
-### 1. Alert Türü Seçimi
+  {emailError && (
+    <AlertInline
+      variant="error"
+      message={t('validation.invalidEmail')}
+    />
+  )}
+</View>
+```
 
+#### System Notice
 ```tsx
-// Kritik işlemler için Modal
-showAlert({ variant: 'error', onConfirm: delete });
-
-// Başarı için Toast
-showToast({ variant: 'success', message: 'Kaydedildi' });
+<AlertBanner
+  variant="warning"
+  title={t('alerts.maintenance')}
+  message={t('alerts.maintenanceMessage')}
+  dismissible
+  onDismiss={() => setShowBanner(false)}
+/>
+```
 
-// Form hatası için Inline
-<AlertInline variant="error" message="Geçersiz değer" />
+## Props Reference
 
-// Sayfa uyarısı için Banner
-<AlertBanner variant="info" message="Sistem bakımda" />
-```
+### AlertBanner
 
-### 2. Message Length
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `variant` | `'info' \| 'success' \| 'warning' \| 'error'` | No | `'info'` | Alert variant |
+| `title` | `string` | No | - | Alert title |
+| `message` | `string` | Yes | - | Alert message |
+| `dismissible` | `boolean` | No | `false` | Show dismiss button |
+| `onDismiss` | `() => void` | No | - | Dismiss callback |
+| `actionLabel` | `string` | No | - | Action button text |
+| `onAction` | `() => void` | No | - | Action callback |
 
-```tsx
-// Kısa ve öz
-showToast({
-  message: 'Kaydedildi', // İyi
-});
+### AlertInline
 
-// Uzun ve açıklayıcı
-showAlert({
-  message: 'Bu işlem geri alınamaz. Devam etmek istediğinizden emin misiniz?', // İyi
-});
-```
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `variant` | `'info' \| 'success' \| 'warning' \| 'error'` | No | `'error'` | Alert variant |
+| `message` | `string` | Yes | - | Error message |
 
-### 3. Variant Kullanımı
+### useAlert Hook
 
-```tsx
-// Başarı
-showToast({ variant: 'success' });
+| Method | Parameters | Description |
+|--------|-----------|-------------|
+| `showToast` | `ToastOptions` | Show temporary notification |
+| `showAlert` | `AlertOptions` | Show confirmation modal |
+| `showBanner` | `BannerOptions` | Show page banner |
 
-// Hata
-showToast({ variant: 'error' });
+### ToastOptions
 
-// Uyarı
-showAlert({ variant: 'warning' });
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `variant` | `'info' \| 'success' \| 'warning' \| 'error'` | Yes | - | Toast variant |
+| `title` | `string` | No | - | Toast title |
+| `message` | `string` | Yes | - | Toast message |
+| `duration` | `number` | No | `3000` | Duration in ms |
 
-// Bilgi
-showBanner({ variant: 'info' });
-```
+### AlertOptions
 
-## Erişilebilirlik
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `variant` | `'info' \| 'success' \| 'warning' \| 'error'` | Yes | - | Alert variant |
+| `title` | `string` | Yes | - | Alert title |
+| `message` | `string` | Yes | - | Alert message |
+| `confirmLabel` | `string` | No | `'OK'` | Confirm button text |
+| `cancelLabel` | `string` | No | - | Cancel button text |
+| `onConfirm` | `() => void` | No | - | Confirm callback |
 
-Alert sistemi, tam erişilebilirlik desteği sunar:
+## Accessibility
 
-- ✅ Screen reader desteği
-- ✅ Semantic anlamlar
-- ✅ Auto-dismiss özelliği
-- ✅ Focus management
-- ✅ Keyboard navigation
+- ✅ Screen reader announces all alerts
+- ✅ Auto-dismiss for non-critical alerts
+- ✅ Focus management for modals
+- ✅ Keyboard navigation support
+- ✅ Semantic alert roles
+- ✅ ARIA live regions
 
-## Performans İpuçları
+## Performance
 
-1. **Auto-dismiss**: Toast'ları otomatik kapatın
-2. **Queue**: Alert'ları sıraya alın
-3. **Unmount**: Kullanılmayan alert'ları unmount edin
+1. **Auto-dismiss**: Toasts dismiss automatically
+2. **Queue**: Multiple alerts queue automatically
+3. **Unmount**: Unmount when closed
+4. **Debounce**: Debounce rapid alert calls
 
-## İlgili Bileşenler
+## Related Components
 
-- [`BaseModal`](../BaseModal/README.md) - Modal bileşeni
-- [`FormField`](../FormField/README.md) - Form alanı
-- [`AtomicButton`](../../atoms/button/README.md) - Buton bileşeni
+- [`BaseModal`](../BaseModal/README.md) - Modal component
+- [`FormField`](../FormField/README.md) - Form field component
+- [`Button`](../../atoms/button/README.md) - Button component
 
-## Lisans
+## License
 
 MIT