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

package/src/molecules/bottom-sheet/README.md

@@ -1,413 +1,376 @@
 # BottomSheet
 
-BottomSheet, ekranın altından açılan modal benzeri bir bileşendir. Filtreleme, seçim veya ekranda kalıcı aksiyonlar için idealdir.
+A modal-like component that opens from the bottom of the screen, ideal for filtering, selection, or on-screen actions.
 
-## Özellikler
+## Import & Usage
 
-- 📱 **4 Preset**: Small, Medium, Large, Full
-- 🎯 **Snap Points**: Birden fazla yükseklik noktası
-- 👆 **Gesture**: Kaydırma ile kapatma
-- 🎨 **Özelleştirilebilir**: Renk ve stil
-- 🔝 **Safe Area**: Safe area desteği
-- ♿ **Erişilebilir**: Tam erişilebilirlik desteği
+```typescript
+import { BottomSheet } from 'react-native-design-system/src/molecules/bottom-sheet';
+```
+
+**Location:** `src/molecules/bottom-sheet/BottomSheet.tsx`
 
-## Kurulum
+## Basic Usage
 
 ```tsx
-import { BottomSheet } from 'react-native-design-system';
+const bottomSheetRef = useRef<BottomSheetRef>(null);
+
+<BottomSheet ref={bottomSheetRef} preset="medium">
+  <View style={{ padding: 24 }}>
+    <YourContent />
+  </View>
+</BottomSheet>
 ```
 
-## Temel Kullanım
+## Strategy
 
-```tsx
-import React, { useRef } from 'react';
-import { View, Button } from 'react-native';
-import { BottomSheet } from 'react-native-design-system';
+**Purpose**: Provide a contextual, gesture-friendly interface for mobile-first interactions from the bottom of the screen.
 
-export const BasicExample = () => {
-  const bottomSheetRef = useRef<BottomSheetRef>(null);
+**When to Use**:
+- Filtering and sorting options
+- Selection from lists (share, actions, options)
+- Form inputs and data entry
+- Contextual actions (edit, delete, share)
+- Multi-step wizards
+- Settings panels
 
-  const openSheet = () => {
-    bottomSheetRef.current?.expand();
-  };
+**When NOT to Use**:
+- For critical confirmations (use BaseModal instead)
+- For simple alerts (use Alert/toast instead)
+- For dropdown menus (use Dropdown/Popover instead)
+- For side panels (use Drawer instead)
+- For desktop-first interfaces (use Modal instead)
 
-  return (
-    <View style={{ flex: 1 }}>
-      <Button title="Bottom Sheet Aç" onPress={openSheet} />
+## Rules
 
-      <BottomSheet
-        ref={bottomSheetRef}
-        preset="medium"
-      >
-        <View style={{ padding: 24 }}>
-          <AtomicText>Bottom Sheet İçeriği</AtomicText>
-        </View>
-      </BottomSheet>
-    </View>
-  );
-};
-```
+### Required
 
-## Preset Yükseklikler
+1. **MUST** provide a close mechanism (ref with close() or onClose callback)
+2. **ALWAYS** use appropriate preset for content length
+3. **MUST** handle back button (Android) and escape key (desktop)
+4. **NEVER** nest bottom sheets inside bottom sheets
+5. **SHOULD** have clear title at top
+6. **MUST** respect safe area insets
 
-```tsx
-<View style={{ gap: 16 }}>
-  {/* Small - %35 */}
-  <BottomSheet ref={ref1} preset="small">
-    <SmallContent />
-  </BottomSheet>
+### Preset Selection
 
-  {/* Medium - %60 (Varsayılan) */}
-  <BottomSheet ref={ref2} preset="medium">
-    <MediumContent />
-  </BottomSheet>
+1. **Small (35%)**: Selections, short lists, simple forms
+2. **Medium (60%)**: Forms with multiple fields, medium lists
+3. **Large (85%)**: Long forms, complex filters, long lists
+4. **Full (100%)**: Full-screen content, complex wizards
 
-  {/* Large - %85 */}
-  <BottomSheet ref={ref3} preset="large">
-    <LargeContent />
-  </BottomSheet>
+### Dismiss Behavior
 
-  {/* Full - %100 */}
-  <BottomSheet ref={ref4} preset="full">
-    <FullContent />
-  </BottomSheet>
-</View>
-```
+1. **Default**: Swipe down enabled
+2. **Critical actions**: Consider disabling swipe, require explicit action
+3. **Always provide close button** (don't rely only on swipe)
 
-## Custom Snap Points
+### Content Guidelines
 
-```tsx
-<BottomSheet
-  ref={bottomSheetRef}
-  snapPoints={['25%', '50%', '75%']}
-  initialIndex={1}
->
-  <Content />
-</BottomSheet>
-```
+1. **Scrollable content**: Use ScrollView for long content
+2. **Actions at bottom**: Place primary actions at bottom
+3. **Handle at top**: Optional visual drag handle
 
-## Custom Background Color
+## Forbidden
+
+❌ **NEVER** do these:
 
 ```tsx
-<BottomSheet
-  ref={bottomSheetRef}
-  backgroundColor="#f8f9fa"
->
+// ❌ No close mechanism
+<BottomSheet ref={ref}>
   <Content />
 </BottomSheet>
-```
-
-## OnChange Callback
-
-```tsx
-const [sheetIndex, setSheetIndex] = useState(-1);
 
-<BottomSheet
-  ref={bottomSheetRef}
-  onChange={(index) => setSheetIndex(index)}
->
+// ❌ Nested bottom sheets
+<BottomSheet ref={ref1}>
   <Content />
+  <BottomSheet ref={ref2}>
+    <NestedContent />
+  </BottomSheet>
 </BottomSheet>
-```
 
-## OnClose Callback
-
-```tsx
-<BottomSheet
-  ref={bottomSheetRef}
-  onClose={() => console.log('Sheet closed')}
->
-  <Content />
+// ❌ Wrong preset choice
+<BottomSheet ref={ref} preset="full">
+  {/* ❌ Use small for simple selection */}
+  <Text>Select option</Text>
 </BottomSheet>
-```
 
-## Örnek Kullanımlar
+// ❌ No title (accessibility issue)
+<BottomSheet ref={ref} onClose={onClose}>
+  <Content /> {/* ❌ Missing title */}
+</BottomSheet>
 
-### Seçim Bottom Sheet
+// ❌ Hardcoded height without scroll
+<BottomSheet ref={ref} preset="small">
+  <View style={{ height: 1000 }}>
+    {/* ❌ Content too long, won't scroll */}
+    <LongContent />
+  </View>
+</BottomSheet>
 
-```tsx
-export const SelectionBottomSheet = ({ ref, options, onSelect }) => {
-  return (
-    <BottomSheet ref={ref} preset="small">
-      <View style={{ padding: 24 }}>
-        <AtomicText type="titleLarge" style={{ marginBottom: 16 }}>
-          Seçim Yapın
-        </AtomicText>
-
-        {options.map((option) => (
-          <Pressable
-            key={option.id}
-            style={{ padding: 16 }}
-            onPress={() => {
-              onSelect(option);
-              ref.current?.close();
-            }}
-          >
-            <AtomicText type="bodyLarge">{option.label}</AtomicText>
-          </Pressable>
-        ))}
-      </View>
-    </BottomSheet>
-  );
-};
+// ❌ Actions at top (bad UX)
+<BottomSheet ref={ref}>
+  <View style={{ padding: 16 }}>
+    <Button title="Save" /> {/* ❌ Should be at bottom */}
+  </View>
+  <Content />
+</BottomSheet>
 ```
 
-### Paylaşım Bottom Sheet
-
-```tsx
-export const ShareBottomSheet = ({ ref, item, onShare }) => {
-  const shareOptions = [
-    { id: 'copy', icon: 'copy-outline', label: 'Linki Kopyala' },
-    { id: 'whatsapp', icon: 'logo-whatsapp', label: 'WhatsApp' },
-    { id: 'twitter', icon: 'logo-twitter', label: 'Twitter' },
-    { id: 'facebook', icon: 'logo-facebook', label: 'Facebook' },
-  ];
-
-  return (
-    <BottomSheet ref={ref} preset="small">
-      <View style={{ padding: 24 }}>
-        <AtomicText type="titleLarge" style={{ marginBottom: 16 }}>
-          Paylaş
-        </AtomicText>
-
-        {shareOptions.map((option) => (
-          <Pressable
-            key={option.id}
-            style={{ flexDirection: 'row', alignItems: 'center', padding: 16 }}
-            onPress={() => onShare(option.id)}
-          >
-            <AtomicIcon name={option.icon} size="lg" style={{ marginRight: 16 }} />
-            <AtomicText type="bodyLarge">{option.label}</AtomicText>
-          </Pressable>
-        ))}
-      </View>
-    </BottomSheet>
-  );
-};
-```
+## Best Practices
 
-### Filtre Bottom Sheet
+### Selection Sheet
 
+✅ **DO**:
 ```tsx
-export const FilterBottomSheet = ({ ref, filters, onApply }) => {
-  const [localFilters, setLocalFilters] = useState(filters);
-
-  return (
-    <BottomSheet ref={ref} preset="large">
-      <View style={{ padding: 24 }}>
-        <View style={{ flexDirection: 'row', justifyContent: 'space-between', marginBottom: 24 }}>
-          <AtomicText type="titleLarge">Filtrele</AtomicText>
-          <Pressable onPress={() => ref.current?.close()}>
-            <AtomicIcon name="close" size="md" />
-          </Pressable>
-        </View>
-
-        {/* Filtre seçenekleri */}
-        <FilterOptions
-          filters={localFilters}
-          onChange={setLocalFilters}
-        />
-
-        <View style={{ flexDirection: 'row', gap: 16, marginTop: 24 }}>
-          <Button
-            title="Temizle"
-            mode="outlined"
-            style={{ flex: 1 }}
-            onPress={() => setLocalFilters({})}
-          />
-          <Button
-            title="Uygula"
-            mode="contained"
-            style={{ flex: 1 }}
-            onPress={() => onApply(localFilters)}
-          />
-        </View>
-      </View>
-    </BottomSheet>
-  );
-};
+<BottomSheet ref={ref} preset="small">
+  <View style={{ padding: 24 }}>
+    <AtomicText type="titleLarge" style={{ marginBottom: 16 }}>
+      Select Option
+    </AtomicText>
+    {options.map((option) => (
+      <Pressable
+        key={option.id}
+        style={{ padding: 16 }}
+        onPress={() => {
+          onSelect(option);
+          ref.current?.close();
+        }}
+      >
+        <AtomicText type="bodyLarge">{option.label}</AtomicText>
+      </Pressable>
+    ))}
+  </View>
+</BottomSheet>
 ```
 
-### Ayarlar Bottom Sheet
-
+❌ **DON'T**:
 ```tsx
-export const SettingsBottomSheet = ({ ref }) => {
-  return (
-    <BottomSheet ref={ref} preset="medium">
-      <View style={{ padding: 24 }}>
-        <AtomicText type="titleLarge" style={{ marginBottom: 24 }}>
-          Ayarlar
-        </AtomicText>
-
-        <SettingItem icon="notifications-outline" label="Bildirimler" />
-        <SettingItem icon="moon-outline" label="Karanlık Mod" />
-        <SettingItem icon="globe-outline" label="Dil" />
-        <SettingItem icon="information-circle-outline" label="Hakkında" />
-      </View>
-    </BottomSheet>
-  );
-};
+// ❌ No close after selection
+<BottomSheet ref={ref} preset="small">
+  {options.map((option) => (
+    <Pressable onPress={() => onSelect(option)}>
+      <AtomicText>{option.label}</AtomicText>
+    </Pressable>
+  ))}
+</BottomSheet>
 ```
 
-### Eylem Bottom Sheet
+### Filter Sheet
 
+✅ **DO**:
 ```tsx
-export const ActionBottomSheet = ({ ref, item, onAction }) => {
-  const actions = [
-    { id: 'edit', icon: 'create-outline', label: 'Düzenle', color: 'primary' },
-    { id: 'share', icon: 'share-outline', label: 'Paylaş', color: 'primary' },
-    { id: 'archive', icon: 'archive-outline', label: 'Arşivle', color: 'primary' },
-    { id: 'delete', icon: 'trash-outline', label: 'Sil', color: 'error' },
-  ];
-
-  return (
-    <BottomSheet ref={ref} preset="small">
-      <View style={{ padding: 8 }}>
-        {actions.map((action) => (
-          <Pressable
-            key={action.id}
-            style={{
-              flexDirection: 'row',
-              alignItems: 'center',
-              padding: 16,
-              borderBottomWidth: 1,
-              borderBottomColor: '#e0e0e0',
-            }}
-            onPress={() => onAction(action.id)}
-          >
-            <AtomicIcon
-              name={action.icon}
-              size="md"
-              color={action.color}
-              style={{ marginRight: 16 }}
-            />
-            <AtomicText
-              type="bodyLarge"
-              color={action.color}
-            >
-              {action.label}
-            </AtomicText>
-          </Pressable>
-        ))}
-      </View>
-    </BottomSheet>
-  );
-};
-```
-
-## Ref Methods
+<BottomSheet ref={ref} preset="large">
+  <View style={{ padding: 24 }}>
+    <View style={{ flexDirection: 'row', justifyContent: 'space-between' }}>
+      <AtomicText type="titleLarge">Filter</AtomicText>
+      <Pressable onPress={() => ref.current?.close()}>
+        <AtomicIcon name="close" />
+      </Pressable>
+    </View>
 
-### BottomSheetRef
+    <ScrollView style={{ marginTop: 16 }}>
+      <FilterOptions filters={filters} onChange={setFilters} />
+    </ScrollView>
 
-```typescript
-interface BottomSheetRef {
-  snapToIndex(index: number): void;    // Index'e git
-  snapToPosition(): void;               // En üste git
-  expand(): void;                       // Genişlet
-  collapse(): void;                     // Daralt
-  close(): void;                        // Kapat
-}
+    <View style={{ flexDirection: 'row', gap: 16, marginTop: 24 }}>
+      <Button title="Clear" variant="ghost" style={{ flex: 1 }} onPress={handleClear} />
+      <Button title="Apply" style={{ flex: 1 }} onPress={handleApply} />
+    </View>
+  </View>
+</BottomSheet>
 ```
 
-### Kullanım
-
+### Preset Choice
+
+✅ **DO**:
+- Small: Simple selections (3-5 items)
+- Medium: Forms with 3-5 fields
+- Large: Long forms, complex filters
+- Full: Multi-step wizards, complex content
+
+❌ **DON'T**:
+- Use full preset for simple selection
+- Use small preset for long forms
+- Use same preset for all use cases
+
+## AI Coding Guidelines
+
+### For AI Agents
+
+When generating BottomSheet components, follow these rules:
+
+1. **Always import from correct path**:
+   ```typescript
+   import { BottomSheet } from 'react-native-design-system/src/molecules/bottom-sheet';
+   ```
+
+2. **Always provide ref and close mechanism**:
+   ```tsx
+   const ref = useRef<BottomSheetRef>(null);
+
+   <BottomSheet ref={ref} onClose={handleClose}>
+     {content}
+   </BottomSheet>
+   ```
+
+3. **Always choose appropriate preset**:
+   ```tsx
+   // ✅ Good - preset by content type
+   const getPreset = (type: 'selection' | 'form' | 'filter') => {
+     switch (type) {
+       case 'selection': return 'small';
+       case 'form': return 'medium';
+       case 'filter': return 'large';
+       default: return 'medium';
+     }
+   };
+   ```
+
+4. **Always handle close actions**:
+   ```tsx
+   // ✅ Good - close after action
+   const handleSelect = (option) => {
+     onSelect(option);
+     ref.current?.close();
+   };
+
+   // ❌ Bad - no close
+   const handleSelect = (option) => {
+     onSelect(option);
+     // Sheet stays open
+   };
+   ```
+
+5. **Always use ScrollView for long content**:
+   ```tsx
+   // ✅ Good - scrollable content
+   <BottomSheet ref={ref} preset="medium">
+     <View style={{ padding: 24 }}>
+       <AtomicText type="titleLarge">Title</AtomicText>
+       <ScrollView style={{ marginTop: 16 }}>
+         <LongFormContent />
+       </ScrollView>
+       <View style={{ marginTop: 24 }}>
+         <Button title="Save" onPress={handleSave} />
+       </View>
+     </View>
+   </BottomSheet>
+   ```
+
+### Common Patterns
+
+#### Selection Bottom Sheet
 ```tsx
-const ref = useRef<BottomSheetRef>(null);
-
-// Aç
-ref.current?.expand();
-
-// Kapat
-ref.current?.close();
-
-// Snap point'e git
-ref.current?.snapToIndex(1);
-```
-
-## Props
-
-### BottomSheetProps
-
-| Prop | Tip | Varsayılan | Açıklama |
-|------|-----|------------|----------|
-| `children` | `ReactNode` | - **(Zorunlu)** | Sheet içeriği |
-| `preset` | `BottomSheetPreset` | `'medium'` | Yükseklik preset'i |
-| `snapPoints` | `(number \| string)[]` | - | Custom snap points |
-| `initialIndex` | `number` | - | Başlangıç index'i |
-| `backgroundColor` | `string` | - | Arka plan rengi |
-| `onChange` | `(index: number) => void` | - | Değişiklik callback'i |
-| `onClose` | `() => void` | - | Kapatma callback'i |
-
-### BottomSheetPreset
-
-```typescript
-type BottomSheetPreset =
-  | 'small'   // %35
-  | 'medium'  // %60 (varsayılan)
-  | 'large'   // %85
-  | 'full';   // %100
+<BottomSheet ref={ref} preset="small">
+  <View style={{ padding: 24 }}>
+    <AtomicText type="titleLarge">Select Option</AtomicText>
+    <ScrollView style={{ marginTop: 16 }}>
+      {options.map((option) => (
+        <Pressable
+          key={option.id}
+          style={{ padding: 16 }}
+          onPress={() => {
+            onSelect(option);
+            ref.current?.close();
+          }}
+        >
+          <AtomicText>{option.label}</AtomicText>
+        </Pressable>
+      ))}
+    </ScrollView>
+  </View>
+</BottomSheet>
 ```
 
-## Best Practices
-
-### 1. Preset Seçimi
-
+#### Filter Bottom Sheet
 ```tsx
-// Kısa içerik için
-<BottomSheet preset="small" />
-
-// Orta içerik için
-<BottomSheet preset="medium" />
+<BottomSheet ref={ref} preset="large">
+  <View style={{ padding: 24 }}>
+    <View style={{ flexDirection: 'row', justifyContent: 'space-between', marginBottom: 16 }}>
+      <AtomicText type="titleLarge">Filter</AtomicText>
+      <Pressable onPress={() => ref.current?.close()}>
+        <AtomicIcon name="close" size="md" />
+      </Pressable>
+    </View>
 
-// Uzun içerik için
-<BottomSheet preset="large" />
+    <ScrollView>
+      <FilterOptions filters={filters} onChange={setFilters} />
+    </ScrollView>
 
-// Tam ekran için
-<BottomSheet preset="full" />
+    <View style={{ flexDirection: 'row', gap: 12, marginTop: 24 }}>
+      <Button title="Clear" variant="ghost" style={{ flex: 1 }} onPress={handleClear} />
+      <Button title="Apply" style={{ flex: 1 }} onPress={handleApply} />
+    </View>
+  </View>
+</BottomSheet>
 ```
 
-### 2. Snap Points
-
+#### Share Bottom Sheet
 ```tsx
-// Birden fazla nokta
-<BottomSheet
-  snapPoints={['25%', '50%', '75%']}
-  initialIndex={1}
-/>
+<BottomSheet ref={ref} preset="small">
+  <View style={{ padding: 24 }}>
+    <AtomicText type="titleLarge" style={{ marginBottom: 16 }}>
+      Share
+    </AtomicText>
+    {shareOptions.map((option) => (
+      <Pressable
+        key={option.id}
+        style={{ flexDirection: 'row', alignItems: 'center', padding: 16 }}
+        onPress={() => {
+          onShare(option.id);
+          ref.current?.close();
+        }}
+      >
+        <AtomicIcon name={option.icon} size="lg" style={{ marginRight: 16 }} />
+        <AtomicText type="bodyLarge">{option.label}</AtomicText>
+      </Pressable>
+    ))}
+  </View>
+</BottomSheet>
 ```
 
-### 3. Kapatma
+## Props Reference
 
-```tsx
-// Manuel kapatma
-ref.current?.close();
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `ref` | `BottomSheetRef` | Yes | - | Sheet ref for control |
+| `children` | `ReactNode` | Yes | - | Sheet content |
+| `preset` | `'small' \| 'medium' \| 'large' \| 'full'` | No | `'medium'` | Height preset |
+| `snapPoints` | `(number \| string)[]` | No | - | Custom snap points |
+| `initialIndex` | `number` | No | - | Initial snap index |
+| `backgroundColor` | `string` | No | - | Background color |
+| `onChange` | `(index: number) => void` | No | - | Index change callback |
+| `onClose` | `() => void` | No | - | Close callback |
 
-// Overlay tıklama ile otomatik
-<BottomSheet onClose={handleClose} />
-```
+### Ref Methods
 
-## Erişilebilirlik
+- `expand()`: Open sheet
+- `close()`: Close sheet
+- `snapToIndex(index)`: Go to snap point
 
-BottomSheet, tam erişilebilirlik desteği sunar:
+## Accessibility
 
-- ✅ Screen reader desteği
-- ✅ Touch uygun boyut
-- ✅ Escape key (web)
-- ✅ Focus trap
-- ✅ Accessibility label
+- ✅ Screen reader announces sheet title and content
+- ✅ Touch target size maintained (min 44x44pt)
+- ✅ Escape key handling (desktop)
+- ✅ Focus trap within sheet
+- ✅ Swipe gesture for dismiss
+- ✅ Back button handling (mobile)
 
-## Performans İpuçları
+## Performance Tips
 
-1. **Lazy Loading**: İçeriği lazy load edin
-2. **Unmount**: Kapatıldığında unmount edin
-3. **Memoization**: İçeriği memo edin
+1. **Lazy loading**: Load content only when sheet opens
+2. **Memoization**: Memo sheet content to prevent re-renders
+3. **Unmount**: Consider unmounting when closed for heavy content
+4. **ScrollView**: Always use ScrollView for long lists
 
-## İlgili Bileşenler
+## Related Components
 
-- [`BaseModal`](../BaseModal/README.md) - Modal bileşeni
-- [`FilterBottomSheet`](./FilterBottomSheet/README.md) - Filtre sheet'i
-- [`AtomicButton`](../../atoms/button/README.md) - Buton bileşeni
+- [`BaseModal`](../BaseModal/README.md) - Modal component for critical actions
+- [`FormField`](../FormField/README.md) - Form field component
+- [`Button`](../../atoms/button/README.md) - Button component
 
-## Lisans
+## License
 
 MIT