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

package/src/atoms/AtomicFab.README.md

@@ -1,421 +1,263 @@
-# AtomicFab
+# AtomicFab (Floating Action Button)
 
-AtomicFab (Floating Action Button), Material Design 3 uyumlu bir yüzen aksiyon butonudur. Ekranın sağ alt köşesinde bulunur ve bir ekrandaki birincil eylemi temsil eder.
+A Material Design 3 floating action button for primary screen actions.
 
-## Özellikler
+## Import & Usage
 
-- 🎯 **Primary Action**: Ana eylem için buton
-- 📏 **3 Size**: Small (40px), Medium (56px), Large (72px)
-- 🎨 **3 Variant**: Primary, Secondary, Surface
-- 📍 **Responsive**: Otomatik pozisyonlama
-- 🔝 **Safe Area**: Tab bar ve safe area uyumlu
-- ♿ **Erişilebilir**: Tam erişilebilirlik desteği
-
-## Önemli Not
+```typescript
+import { AtomicFab } from 'react-native-design-system/src/atoms/AtomicFab';
+```
 
-⚠️ **FAB mutlaka ScreenLayout seviyesinde kullanılmalı, ScrollView içinde kullanılmamalıdır!**
+**Location:** `src/atoms/AtomicFab.tsx`
 
-## Kurulum
+## Basic Usage
 
 ```tsx
-import { AtomicFab } from 'react-native-design-system';
+<ScreenLayout>
+  <ScrollView>{/* Content */}</ScrollView>
+  <AtomicFab icon="add" onPress={handleAdd} />
+</ScreenLayout>
 ```
 
-## Temel Kullanım
+## Strategy
 
-```tsx
-import React from 'react';
-import { View, ScrollView } from 'react-native';
-import { AtomicFab, ScreenLayout } from 'react-native-design-system';
-
-export const BasicExample = () => {
-  const handleAdd = () => {
-    console.log('Yeni öğe ekle');
-  };
-
-  return (
-    <ScreenLayout>
-      <ScrollView>
-        {/* İçerik */}
-      </ScrollView>
-
-      <AtomicFab
-        icon="add"
-        onPress={handleAdd}
-      />
-    </ScreenLayout>
-  );
-};
-```
+**Purpose**: Promote the primary action on a screen.
 
-## Variant'lar
+**When to Use**:
+- Primary screen action (add item, create new)
+- Frequently used action
+- Single positive action (create, add, share)
+- Destructive action when it's the only option
 
-```tsx
-<View style={{ gap: 16 }}>
-  {/* Primary (Varsayılan) */}
-  <AtomicFab
-    icon="add"
-    variant="primary"
-    onPress={() => {}}
-  />
-
-  {/* Secondary */}
-  <AtomicFab
-    icon="create"
-    variant="secondary"
-    onPress={() => {}}
-  />
-
-  {/* Surface */}
-  <AtomicFab
-    icon="share"
-    variant="surface"
-    onPress={() => {}}
-  />
-</View>
-```
+**When NOT to Use**:
+- In ScrollView (MUST be at ScreenLayout level)
+- For multiple actions of equal importance
+- For non-primary actions
+- For actions that are context-specific to list items
 
-## Boyutlar
+## Rules
 
-```tsx
-<View style={{ gap: 16 }}>
-  {/* Small */}
-  <AtomicFab
-    icon="add"
-    size="sm"
-    onPress={() => {}}
-  />
-
-  {/* Medium (Varsayılan) */}
-  <AtomicFab
-    icon="add"
-    size="md"
-    onPress={() => {}}
-  />
-
-  {/* Large */}
-  <AtomicFab
-    icon="add"
-    size="lg"
-    onPress={() => {}}
-  />
-</View>
-```
+### Required
 
-## Disabled State
+1. **MUST** be at ScreenLayout level (NOT in ScrollView)
+2. **ALWAYS** provide `icon` and `onPress`
+3. **SHOULD** use `primary` variant for main action
+4. **MUST** have accessibility label
+5. **ALWAYS** use appropriate icon for action
+6. **SHOULD** be the only FAB on screen
+7. **MUST** not overlap important content
 
-```tsx
-<AtomicFab
-  icon="add"
-  disabled
-  onPress={() => {}}
-/>
-```
+### Positioning
+
+1. **Default**: Bottom-right corner
+2. **Safe area**: Respects safe area insets
+3. **Above navigation**: Above tab bar if present
+4. **Manual**: Can position manually with style
 
-## Custom Style
+### Variants
+
+1. **primary**: Main action (default)
+2. **secondary**: Secondary action
+3. **surface**: Surface-level action
+
+## Forbidden
+
+❌ **NEVER** do these:
 
 ```tsx
+// ❌ FAB in ScrollView
+<ScrollView>
+  <Content />
+  <AtomicFab icon="add" onPress={handleAdd} /> {/* ❌ Wrong level */}
+</ScrollView>
+
+// ❌ Missing accessibility
 <AtomicFab
   icon="add"
   onPress={handleAdd}
-  style={{
-    bottom: 100,
-    right: 20,
-  }}
+  // ❌ No accessibilityLabel
 />
-```
 
-## Örnek Kullanımlar
+// ❌ Wrong icon for action
+<AtomicFab
+  icon="trash" {/* ❌ FAB should be positive action */}
+  onPress={handleDelete}
+/>
 
-### Yeni Öğe Ekleme
+// ❌ Multiple FABs
+<ScreenLayout>
+  <AtomicFab icon="add" onPress={handleAdd} />
+  <AtomicFab icon="edit" onPress={handleEdit} /> {/* ❌ Too many */}
+</ScreenLayout>
 
-```tsx
-export const ItemList = () => {
-  const navigation = useNavigation();
-
-  return (
-    <ScreenLayout>
-      <FlatList
-        data={items}
-        keyExtractor={(item) => item.id}
-        renderItem={({ item }) => <ItemCard item={item} />}
-      />
-
-      <AtomicFab
-        icon="add"
-        onPress={() => navigation.navigate('AddItem')}
-        accessibilityLabel="Yeni öğe ekle"
-      />
-    </ScreenLayout>
-  );
-};
+// ❌ Unnecessary variant
+<AtomicFab
+  icon="share"
+  variant="surface" {/* Should use default primary */}
+  onPress={handleShare}
+/>
 ```
 
-### Mesaj Oluşturma
-
-```tsx
-export const ChatList = () => {
-  return (
-    <ScreenLayout>
-      <FlatList
-        data={conversations}
-        keyExtractor={(item) => item.id}
-        renderItem={({ item }) => <ConversationCard item={item} />}
-      />
-
-      <AtomicFab
-        icon="chatbubble-outline"
-        onPress={() => console.log('Yeni mesaj')}
-        accessibilityLabel="Yeni mesaj"
-      />
-    </ScreenLayout>
-  );
-};
-```
+## Best Practices
 
-### Fotoğraf Çekme
+### ScreenLayout Level
 
+✅ **DO**:
 ```tsx
-export const PhotoGallery = () => {
-  const handleTakePhoto = () => {
-    launchCamera();
-  };
-
-  return (
-    <ScreenLayout>
-      <FlatList
-        data={photos}
-        numColumns={3}
-        renderItem={({ item }) => <PhotoItem photo={item} />}
-      />
-
-      <AtomicFab
-        icon="camera-outline"
-        onPress={handleTakePhoto}
-        accessibilityLabel="Fotoğraf çek"
-      />
-    </ScreenLayout>
-  );
-};
+<ScreenLayout>
+  <ScrollView>
+    <Content />
+  </ScrollView>
+  <AtomicFab icon="add" onPress={handleAdd} />
+</ScreenLayout>
 ```
 
-### Konum Oluşturma
-
+❌ **DON'T**:
 ```tsx
-export const MapScreen = () => {
-  const handleAddLocation = () => {
-    console.log('Konum ekle');
-  };
-
-  return (
-    <ScreenLayout>
-      <MapView style={{ flex: 1 }} />
-
-      <AtomicFab
-        icon="location-outline"
-        variant="secondary"
-        onPress={handleAddLocation}
-        accessibilityLabel="Konum ekle"
-      />
-    </ScreenLayout>
-  );
-};
+// ❌ In ScrollView
+<ScrollView>
+  <Content />
+  <AtomicFab icon="add" onPress={handleAdd} />
+</ScrollView>
 ```
 
-### Arama
+### Icon Selection
 
+✅ **DO**:
 ```tsx
-export const ContactList = () => {
-  const handleCall = () => {
-    console.log('Ara');
-  };
-
-  return (
-    <ScreenLayout>
-      <FlatList
-        data={contacts}
-        keyExtractor={(item) => item.id}
-        renderItem={({ item }) => <ContactCard contact={item} />}
-      />
-
-      <AtomicFab
-        icon="call-outline"
-        variant="surface"
-        onPress={handleCall}
-        accessibilityLabel="Ara"
-      />
-    </ScreenLayout>
-  );
-};
+// ✅ Positive, clear actions
+<AtomicFab icon="add" onPress={handleAdd} />
+<AtomicFab icon="create" onPress={handleEdit} />
+<AtomicFab icon="chatbubble" onPress={handleMessage} />
 ```
 
-### Farklı Eylemler
-
+❌ **DON'T**:
 ```tsx
-export const Dashboard = () => {
-  return (
-    <ScreenLayout>
-      <ScrollView contentContainerStyle={{ padding: 16 }}>
-        <DashboardCards />
-      </ScrollView>
-
-      {/* İlk FAB - Ana eylem */}
-      <AtomicFab
-        icon="add"
-        onPress={() => console.log('Ana eylem')}
-        style={{ right: 80 }}
-      />
-
-      {/* İkinci FAB - İkincil eylem */}
-      <AtomicFab
-        icon="settings-outline"
-        variant="secondary"
-        size="sm"
-        onPress={() => console.log('İkincil eylem')}
-      />
-    </ScreenLayout>
-  );
-};
+// ❌ Negative actions
+<AtomicFab icon="trash" onPress={handleDelete} />
+<AtomicFab icon="close" onPress={handleClose} />
 ```
 
-## Props
-
-### AtomicFabProps
-
-| Prop | Tip | Varsayılan | Açıklama |
-|------|-----|------------|----------|
-| `icon` | `string` | - **(Zorunlu)** | İkon ismi (Ionicons) |
-| `onPress` | `() => void` | - **(Zorunlu)** | Tıklama olayı |
-| `variant` | `FabVariant` | `'primary'` | FAB variant'ı |
-| `size` | `FabSize` | `'md'` | FAB boyutu |
-| `disabled` | `boolean` | `false` | Devre dışı |
-| `activeOpacity` | `number` | `0.7` | Tıklama opaklığı |
-| `accessibilityLabel` | `string` | - | Erişilebilirlik etiketi |
-| `style` | `StyleProp<ViewStyle>` | - | Özel stil |
-| `testID` | `string` | - | Test ID'si |
+### Accessibility
 
-### FabVariant
-
-```typescript
-type FabVariant =
-  | 'primary'    // Ana eylem (varsayılan)
-  | 'secondary'  // İkincil eylem
-  | 'surface';   // Yüzey eylemi
+✅ **DO**:
+```tsx
+<AtomicFab
+  icon="add"
+  onPress={handleAdd}
+  accessibilityLabel="Add new item"
+/>
 ```
 
-### FabSize
-
-```typescript
-type FabSize =
-  | 'sm'  // Small (40px)
-  | 'md'  // Medium (56px, varsayılan)
-  | 'lg'; // Large (72px)
+❌ **DON'T**:
+```tsx
+// ❌ No label
+<AtomicFab icon="add" onPress={handleAdd} />
 ```
 
-## Best Practices
-
-### 1. Doğru Kullanım
-
+## AI Coding Guidelines
+
+### For AI Agents
+
+When generating AtomicFab components, follow these rules:
+
+1. **Always place at ScreenLayout level**:
+   ```tsx
+   // ✅ Good
+   <ScreenLayout>
+     <ScrollView>{/* Content */}</ScrollView>
+     <AtomicFab icon="add" onPress={handleAdd} />
+   </ScreenLayout>
+
+   // ❌ Bad
+   <ScrollView>
+     <Content />
+     <AtomicFab icon="add" onPress={handleAdd} />
+   </ScrollView>
+   ```
+
+2. **Always use positive actions**:
+   ```tsx
+   // ✅ Good
+   <AtomicFab icon="add" onPress={handleAdd} />
+   <AtomicFab icon="create" onPress={handleCreate} />
+
+   // ❌ Bad
+   <AtomicFab icon="trash" onPress={handleDelete} />
+   <AtomicFab icon="close" onPress={handleClose} />
+   ```
+
+3. **Always provide accessibility label**:
+   ```tsx
+   // ✅ Good
+   <AtomicFab
+     icon="add"
+     onPress={handleAdd}
+     accessibilityLabel="Create new item"
+   />
+
+   // ❌ Bad
+   <AtomicFab icon="add" onPress={handleAdd} />
+   ```
+
+4. **Never use multiple FABs**:
+   ```tsx
+   // ❌ Bad - multiple FABs
+   <ScreenLayout>
+     <AtomicFab icon="add" />
+     <AtomicFab icon="edit" />
+   </ScreenLayout>
+   ```
+
+### Common Patterns
+
+#### Basic FAB
 ```tsx
-// ✅ DOĞRU - ScreenLayout seviyesinde
 <ScreenLayout>
-  <ScrollView>
-    {/* İçerik */}
-  </ScrollView>
+  <ScrollView>{/* Content */}</ScrollView>
   <AtomicFab icon="add" onPress={handleAdd} />
 </ScreenLayout>
-
-// ❌ YANLIŞ - ScrollView içinde
-<ScrollView>
-  <AtomicFab icon="add" onPress={handleAdd} />
-</ScrollView>
 ```
 
-### 2. İkon Seçimi
-
+#### With Custom Position
 ```tsx
-// Ekleme işlemi
-<AtomicFab icon="add" />
-
-// Düzenleme
-<AtomicFab icon="create" />
-
-// Mesajlaşma
-<AtomicFab icon="chatbubble-outline" />
-
-// Paylaşım
-<AtomicFab icon="share-outline" />
-
-// Arama
-<AtomicFab icon="call-outline" />
+<AtomicFab
+  icon="add"
+  onPress={handleAdd}
+  style={{ bottom: 100 }}
+/>
 ```
 
-### 3. Variant Seçimi
-
-```tsx
-// Ana eylem
-<AtomicFab variant="primary" icon="add" />
-
-// İkincil eylem
-<AtomicFab variant="secondary" icon="create" />
+## Props Reference
 
-// Alternatif eylem
-<AtomicFab variant="surface" icon="share" />
-```
-
-## Erişilebilirlik
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `icon` | `string` | Yes | - | Icon name (Ionicons) |
+| `onPress` | `() => void` | Yes | - | Press callback |
+| `variant` | `'primary' \| 'secondary' \| 'surface'` | No | `'primary'` | FAB variant |
+| `size` | `'sm' \| 'md' \| 'lg'` | No | `'md'` | FAB size |
+| `disabled` | `boolean` | No | `false` | Disabled state |
+| `accessibilityLabel` | `string` | No | - | Accessibility label |
 
-AtomicFab, tam erişilebilirlik desteği sunar:
+## Accessibility
 
-- ✅ Touch uygun boyut (minimum 40x40)
-- ✅ Screen reader desteği
+- ✅ Touch target size (min 40x40)
+- ✅ Screen reader support
 - ✅ Accessibility label
 - ✅ Semantic role (button)
-- ✅ Test ID desteği
-
-## Performans İpuçları
-
-1. **OnPress Stabilization**: `onPress` callback'ini `useCallback` ile sarın
-2. **Avoid Re-renders**: FAB'ı gereksiz yere yeniden render etmeyin
-3. **Single FAB**: Genellikle bir ekranda tek FAB olmalıdır
-
-## Material Design 3 Uyumluluğu
-
-Bu bileşen Material Design 3 spesifikasyonlarına uygun olarak tasarlanmıştır:
-
-- ✅ Standart boyutlar (40px, 56px, 72px)
-- ✅ Variant renkleri
-- ✅ Border ile derinlik (gölge yok)
-- ✅ Responsive pozisyonlama
-- ✅ Safe area desteği
-
-## İlgili Bileşenler
-
-- [`AtomicButton`](./button/README.md) - Normal buton
-- [`AtomicIcon`](./AtomicIcon/README.md) - İkon bileşeni
-- [`ScreenLayout`](../layouts/ScreenLayout/README.md) - Ekran düzeni
-
-## Önemli Bilgiler
-
-### FAB Kullanımı
 
-1. **Birincil Eylem**: FAB, ekrandaki en önemli eylem olmalıdır
-2. **Sınırlı Sayı**: Bir ekranda genellikle tek FAB bulunur
-3. **Pozisyon**: Sağ alt köşededir
-4. **Scroll**: İçerik scroll olduğunda sabit kalır
+## Performance Tips
 
-### FAB vs Extended FAB
+1. **Stabilize onPress**: Use useCallback
+2. **Single FAB**: Only one per screen
+3. **Avoid re-renders**: Memo FAB wrapper
 
-Standart FAB (bu bileşen):
-- Dairesel şekil
-- Sadece ikon
-- Compact tasarım
+## Related Components
 
-Extended FAB (farklı bileşen):
-- Dikdörtgen/Pill şekil
-- İkon + metin
-- Daha fazla yer kaplar
+- [`AtomicButton`](./AtomicButton.README.md) - Regular button
+- [`AtomicIcon`](./AtomicIcon.README.md) - Icon component
+- [`ScreenLayout`](../layouts/ScreenLayout) - Screen layout
 
-## Lisans
+## License
 
 MIT