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

package/src/atoms/AtomicAvatar.README.md

@@ -1,483 +1,370 @@
 # AtomicAvatar
 
-AtomicAvatar, kullanıcı profil resimlerini göstermek için tasarlanmış çok yönlü bir avatar bileşenidir. Resim yoksa ismin baş harflerini gösterir.
+A user profile image component with fallback to initials when image is not available.
 
-## Özellikler
+## Import & Usage
 
-- 🖼️ **Image Support**: URI veya require ile resim yükleme
-- 🔤 **Initials Fallback**: Resim yoksa baş harfler
-- 📏 **6 Size**: xs, sm, md, lg, xl, xxl
-- 🎨 **Özelleştirilebilir**: Renk, border, stil
-- ♿ **Erişilebilir**: Tam erişilebilirlik desteği
-- 🌐 **Responsive**: Otomatik boyutlandırma
+```typescript
+import { AtomicAvatar } from 'react-native-design-system/src/atoms/AtomicAvatar';
+```
 
-## Kurulum
+**Location:** `src/atoms/AtomicAvatar.tsx`
+
+## Basic Usage
 
 ```tsx
-import { AtomicAvatar } from 'react-native-design-system';
+<AtomicAvatar name="John Doe" />
 ```
 
-## Temel Kullanım
+## Strategy
 
-```tsx
-import React from 'react';
-import { View } from 'react-native';
-import { AtomicAvatar } from 'react-native-design-system';
-
-export const BasicExample = () => {
-  return (
-    <View style={{ padding: 16 }}>
-      {/* Resim ile */}
-      <AtomicAvatar
-        source={{ uri: 'https://example.com/avatar.jpg' }}
-      />
+**Purpose**: Display user profile pictures with automatic fallback to initials when image unavailable.
 
-      {/* İsim ile (baş harfler) */}
-      <AtomicAvatar
-        name="Ahmet Yılmaz"
-      />
-    </View>
-  );
-};
-```
+**When to Use**:
+- User profile images in lists or cards
+- Comment/user activity sections
+- Navigation headers with user info
+- Team member displays
+- Anywhere user identity needs visual representation
 
-## Boyutlar
+**When NOT to Use**:
+- For non-user images (products, content) - use Image component
+- When initials don't make sense (company logos, icons)
+- For decorative images without user context
 
-```tsx
-<View style={{ flexDirection: 'row', gap: 8, alignItems: 'center' }}>
-  {/* Extra Small */}
-  <AtomicAvatar
-    name="AY"
-    size="xs"
-  />
+## Rules
 
-  {/* Small */}
-  <AtomicAvatar
-    name="Ahmet"
-    size="sm"
-  />
+### Required
 
-  {/* Medium (Varsayılan) */}
-  <AtomicAvatar
-    name="Ahmet"
-    size="md"
-  />
+1. **MUST** provide either `source` or `name` prop
+2. **ALWAYS** use appropriate size for context
+3. **SHOULD** provide `name` even when using image (for fallback)
+4. **MUST** maintain accessible labeling
+5. **ALWAYS** handle image loading errors gracefully
+6. **SHOULD** use consistent sizes across related contexts
+7. **MUST** not use for non-user avatars
 
-  {/* Large */}
-  <AtomicAvatar
-    name="Ahmet"
-    size="lg"
-  />
+### Size Selection
 
-  {/* Extra Large */}
-  <AtomicAvatar
-    name="Ahmet"
-    size="xl"
-  />
+1. **xs (24px)**: Inline text, tiny mentions
+2. **sm (32px)**: List items, compact displays
+3. **md (40px)**: Default, most use cases
+4. **lg (56px)**: Cards, profile headers
+5. **xl (80px)**: Profile pages, large displays
+6. **xxl (120px)**: Hero sections, featured profiles
 
-  {/* Extra Extra Large */}
-  <AtomicAvatar
-    name="Ahmet"
-    size="xxl"
-  />
-</View>
-```
+### Initials Fallback
+
+1. **Single name**: First letter
+2. **Two names**: First letter of each (John Doe → JD)
+3. **Three+ names**: First letter of first two names
+4. **No name**: Shows "?" placeholder
+
+### Image Loading
+
+1. **Cache images**: Use FastImage or cached images
+2. **Handle errors**: Always provide name fallback
+3. **Lazy load**: In lists, use lazy loading
 
-## Resim ile
+## Forbidden
+
+❌ **NEVER** do these:
 
 ```tsx
-{/* URI ile */}
+// ❌ No source or name
+<AtomicAvatar /> {/* ❌ Shows "?" */}
+
+// ❌ Wrong size for context
+<AtomicList>
+  <AtomicItem>
+    <AtomicAvatar size="xxl" /> {/* ❌ Too large for list */}
+  </AtomicItem>
+</AtomicList>
+
+// ❌ No name fallback
 <AtomicAvatar
-  source={{ uri: 'https://example.com/avatar.jpg' }}
+  source={{ uri: avatarUrl }}
+  // ❌ No name, shows "?" if image fails
 />
 
-{/* Local resim */}
+// ❌ Name for non-user
 <AtomicAvatar
-  source={require('./assets/avatar.png')}
+  name="Product Name"
+  source={{ uri: productImage }}
+  // ❌ Should use Image component
+/>
+
+// ❌ Inconsistent sizes in list
+<FlatList
+  data={users}
+  renderItem={({ item }) => (
+    <UserItem>
+      <AtomicAvatar
+        name={item.name}
+        size={item.index % 2 === 0 ? 'sm' : 'lg'} {/* ❌ Inconsistent */}
+      />
+    </UserItem>
+  )}
 />
 
-{/* Custom size */}
+// ❌ Hardcoded border radius on circular avatar
 <AtomicAvatar
-  source={{ uri: 'https://example.com/avatar.jpg' }}
-  customSize={80}
+  name="John"
+  borderRadius={8} {/* ❌ Avatar is meant to be circular */}
 />
 ```
 
-## Baş Harfler ile
-
-```tsx
-{/* Tek isim */}
-<AtomicAvatar name="Ahmet" /> {/* A */}
-
-{/* İki isim */}
-<AtomicAvatar name="Ahmet Yılmaz" /> {/* AY */}
-
-{/* Üç isim */}
-<AtomicAvatar name="Ahmet Can Yılmaz" /> {/* AC */}
-
-{/* Boş isim */}
-<AtomicAvatar /> {/* ? */}
-```
+## Best Practices
 
-## Custom Renkler
+### Size Selection
 
+✅ **DO**:
 ```tsx
-<View style={{ flexDirection: 'row', gap: 8 }}>
-  {/* Custom background */}
-  <AtomicAvatar
-    name="Ahmet"
-    backgroundColor="#6366f1"
-    textColor="#ffffff"
-  />
+// ✅ List items
+<FlatList
+  data={users}
+  renderItem={({ item }) => (
+    <ListItem>
+      <AtomicAvatar name={item.name} size="sm" />
+    </ListItem>
+  )}
+/>
 
-  {/* Custom text */}
-  <AtomicAvatar
-    name="Ayşe"
-    backgroundColor="#ec4899"
-    textColor="#ffffff"
-  />
-</View>
-```
+// ✅ Profile header
+<AtomicAvatar name={user.name} size="xxl" />
 
-## Border
+// ✅ Default size
+<AtomicAvatar name="John Doe" /> {/* md (40px) */}
+```
 
+❌ **DON'T**:
 ```tsx
-<View style={{ flexDirection: 'row', gap: 8 }}>
-  {/* Border width */}
-  <AtomicAvatar
-    name="Ahmet"
-    borderWidth={2}
-    borderColor="#6366f1"
-  />
-
-  {/* Custom border */}
-  <AtomicAvatar
-    name="Ayşe"
-    borderWidth={3}
-    borderColor="#ec4899"
-  />
-</View>
+// ❌ Wrong sizes
+<ListItem>
+  <AtomicAvatar name="John" size="xxl" /> {/* Too large */}
+</ListItem>
+
+<ProfileHeader>
+  <AtomicAvatar name="John" size="xs" /> {/* Too small */}
+</ProfileHeader>
 ```
 
-## Custom Border Radius
+### Fallback Handling
 
+✅ **DO**:
 ```tsx
-{/* Yuvarlak (varsayılan) */}
+// ✅ Always provide name
 <AtomicAvatar
-  name="Ahmet"
-  size="lg"
+  source={{ uri: user.avatar }}
+  name={user.name} // Fallback to initials
 />
 
-{/* Kare */}
+// ✅ Handle missing data
 <AtomicAvatar
-  name="Ahmet"
-  size="lg"
-  borderRadius={8}
-/>
-
-<!-- Köşeli yuvarlatılmış -->
-<AtomicAvatar
-  name="Ahmet"
-  size="lg"
-  borderRadius={16}
+  name={user.name || 'Unknown User'}
+  source={user.avatar ? { uri: user.avatar } : undefined}
 />
 ```
 
-## Örnek Kullanımlar
-
-### Kullanıcı Listesi
-
+❌ **DON'T**:
 ```tsx
-export const UserList = ({ users }) => {
-  return (
-    <FlatList
-      data={users}
-      keyExtractor={(item) => item.id}
-      renderItem={({ item }) => (
-        <View style={{ flexDirection: 'row', alignItems: 'center', padding: 16 }}>
-          <AtomicAvatar
-            source={item.avatar ? { uri: item.avatar } : undefined}
-            name={item.name}
-            size="md"
-            style={{ marginRight: 12 }}
-          />
-
-          <View>
-            <AtomicText type="bodyLarge" fontWeight="600">
-              {item.name}
-            </AtomicText>
-            <AtomicText type="bodySmall" color="textSecondary">
-              {item.email}
-            </AtomicText>
-          </View>
-        </View>
-      )}
-    />
-  );
-};
-```
-
-### Profil Başlığı
-
-```tsx
-export const ProfileHeader = ({ user }) => {
-  return (
-    <View style={{ alignItems: 'center', padding: 24 }}>
-      <AtomicAvatar
-        source={user.avatar ? { uri: user.avatar } : undefined}
-        name={user.name}
-        size="xxl"
-        borderWidth={3}
-        borderColor={tokens.colors.primary}
-        style={{ marginBottom: 16 }}
-      />
-
-      <AtomicText type="headlineSmall">
-        {user.name}
-      </AtomicText>
+// ❌ No fallback
+<AtomicAvatar
+  source={{ uri: user.avatar }}
+  // Shows "?" if image fails
+/>
 
-      <AtomicText type="bodyMedium" color="textSecondary">
-        @{user.username}
-      </AtomicText>
-    </View>
-  );
-};
+// ❌ Empty name
+<AtomicAvatar name="" />
 ```
 
-### Avatar Grubu
+### Avatar Groups
 
+✅ **DO**:
 ```tsx
-export const AvatarGroup = ({ users, max = 3 }) => {
-  const visibleUsers = users.slice(0, max);
-  const remainingCount = users.length - max;
-
-  return (
-    <View style={{ flexDirection: 'row' }}>
-      {visibleUsers.map((user, index) => (
-        <AtomicAvatar
-          key={user.id}
-          source={user.avatar ? { uri: user.avatar } : undefined}
-          name={user.name}
-          size="sm"
-          style={{
-            marginLeft: index > 0 ? -8 : 0,
-            borderWidth: 2,
-            borderColor: tokens.colors.backgroundPrimary,
-          }}
-        />
-      ))}
-
-      {remainingCount > 0 && (
-        <View
-          style={{
-            width: tokens.avatarSizes.sm,
-            height: tokens.avatarSizes.sm,
-            borderRadius: tokens.avatarSizes.sm / 2,
-            backgroundColor: tokens.colors.surfaceVariant,
-            justifyContent: 'center',
-            alignItems: 'center',
-            marginLeft: -8,
-            borderWidth: 2,
-            borderColor: tokens.colors.backgroundPrimary,
-          }}
-        >
-          <AtomicText type="labelSmall">
-            +{remainingCount}
-          </AtomicText>
-        </View>
-      )}
+// ✅ Overlapping avatars
+<View style={{ flexDirection: 'row' }}>
+  {users.slice(0, 3).map((user, index) => (
+    <AtomicAvatar
+      key={user.id}
+      name={user.name}
+      size="sm"
+      style={{ marginLeft: index > 0 ? -8 : 0 }}
+    />
+  ))}
+  {users.length > 3 && (
+    <View style={{
+      width: 32,
+      height: 32,
+      borderRadius: 16,
+      backgroundColor: tokens.colors.surfaceVariant,
+      justifyContent: 'center',
+      alignItems: 'center',
+      marginLeft: -8,
+    }}>
+      <AtomicText type="labelSmall">+{users.length - 3}</AtomicText>
     </View>
-  );
-};
+  )}
+</View>
 ```
 
-### Yorum Bileşeni
+### Status Indicators
 
+✅ **DO**:
 ```tsx
-export const Comment = ({ comment }) => {
-  return (
-    <View style={{ flexDirection: 'row', padding: 16 }}>
-      <AtomicAvatar
-        source={comment.author.avatar ? { uri: comment.author.avatar } : undefined}
-        name={comment.author.name}
-        size="sm"
-        style={{ marginRight: 12 }}
-      />
-
-      <View style={{ flex: 1 }}>
-        <View style={{ flexDirection: 'row', alignItems: 'center', marginBottom: 4 }}>
-          <AtomicText type="bodyMedium" fontWeight="600">
-            {comment.author.name}
-          </AtomicText>
-          <AtomicText type="bodySmall" color="textTertiary" style={{ marginLeft: 8 }}>
-            {comment.timestamp}
-          </AtomicText>
-        </View>
-
-        <AtomicText type="bodyMedium">
-          {comment.text}
-        </AtomicText>
-      </View>
-    </View>
-  );
-};
+// ✅ Online status
+<View style={{ position: 'relative' }}>
+  <AtomicAvatar name={user.name} size="lg" />
+  {user.isOnline && (
+    <View style={{
+      position: 'absolute',
+      bottom: 0,
+      right: 0,
+      width: 14,
+      height: 14,
+      borderRadius: 7,
+      backgroundColor: tokens.colors.success,
+      borderWidth: 2,
+      borderColor: tokens.colors.backgroundPrimary,
+    }} />
+  )}
+</View>
 ```
 
-### Navigasyon
-
+## AI Coding Guidelines
+
+### For AI Agents
+
+When generating AtomicAvatar components, follow these rules:
+
+1. **Always provide name fallback**:
+   ```tsx
+   // ✅ Good
+   <AtomicAvatar
+     source={{ uri: user.avatar }}
+     name={user.name}
+   />
+
+   // ❌ Bad
+   <AtomicAvatar source={{ uri: user.avatar }} />
+   ```
+
+2. **Always use appropriate size**:
+   ```tsx
+   // ✅ Good - size matches context
+   <ListItem>
+     <AtomicAvatar name={user.name} size="sm" />
+   </ListItem>
+   <ProfileHeader>
+     <AtomicAvatar name={user.name} size="xxl" />
+   </ProfileHeader>
+
+   // ❌ Bad - wrong size
+   <ListItem>
+     <AtomicAvatar name={user.name} size="xxl" />
+   </ListItem>
+   ```
+
+3. **Always handle missing data**:
+   ```tsx
+   // ✅ Good - handles missing
+   <AtomicAvatar
+     name={user.name || 'Unknown'}
+     source={user.avatar ? { uri: user.avatar } : undefined}
+   />
+
+   // ❌ Bad - doesn't handle missing
+   <AtomicAvatar name={user.name} source={{ uri: user.avatar }} />
+   ```
+
+4. **Never use for non-user images**:
+   ```tsx
+   // ❌ Bad - non-user avatar
+   <AtomicAvatar
+     name="Product"
+     source={{ uri: productImage }}
+   />
+   // Should use Image component instead
+   ```
+
+### Common Patterns
+
+#### Basic Avatar
 ```tsx
-export const ProfileTab = ({ user }) => {
-  return (
-    <Pressable
-      style={{ flexDirection: 'row', alignItems: 'center', padding: 16 }}
-      onPress={() => navigation.navigate('Profile', { userId: user.id })}
-    >
-      <AtomicAvatar
-        source={user.avatar ? { uri: user.avatar } : undefined}
-        name={user.name}
-        size="md"
-      />
-
-      <View style={{ marginLeft: 12, flex: 1 }}>
-        <AtomicText type="bodyLarge" fontWeight="600">
-          {user.name}
-        </AtomicText>
-        <AtomicText type="bodySmall" color="textSecondary">
-          Profili görüntüle
-        </AtomicText>
-      </View>
-
-      <AtomicIcon name="chevron-forward" size="sm" />
-    </Pressable>
-  );
-};
+<AtomicAvatar name="John Doe" />
 ```
 
-### Online Durumu
-
+#### With Image
 ```tsx
-export const AvatarWithStatus = ({ user, isOnline }) => {
-  return (
-    <View style={{ position: 'relative' }}>
-      <AtomicAvatar
-        source={user.avatar ? { uri: user.avatar } : undefined}
-        name={user.name}
-        size="lg"
-      />
-
-      {isOnline && (
-        <View
-          style={{
-            position: 'absolute',
-            bottom: 0,
-            right: 0,
-            width: 16,
-            height: 16,
-            borderRadius: 8,
-            backgroundColor: tokens.colors.success,
-            borderWidth: 2,
-            borderColor: tokens.colors.backgroundPrimary,
-          }}
-        />
-      )}
-    </View>
-  );
-};
-```
-
-## Props
-
-### AtomicAvatarProps
-
-| Prop | Tip | Varsayılan | Açıklama |
-|------|-----|------------|----------|
-| `source` | `ImageSourcePropType` | - | Resim kaynağı |
-| `name` | `string` | - | Kullanıcı ismi (baş harfler için) |
-| `size` | `AvatarSize` | `'md'` | Avatar boyutu |
-| `customSize` | `number` | - | Özel boyut (px) |
-| `backgroundColor` | `string` | - | Arka plan rengi |
-| `textColor` | `string` | - | Metin rengi |
-| `borderRadius` | `number` | - | Köşe yarıçapı |
-| `borderWidth` | `number` | `0` | Çerçeve kalınlığı |
-| `borderColor` | `string` | - | Çerçeve rengi |
-| `style` | `StyleProp<ViewStyle>` | - | Özel stil |
-| `imageStyle` | `StyleProp<ImageStyle>` | - | Resim stili |
-| `testID` | `string` | - | Test ID'si |
-
-### AvatarSize
-
-```typescript
-type AvatarSize =
-  | 'xs'   // Extra small
-  | 'sm'   // Small
-  | 'md'   // Medium (varsayılan)
-  | 'lg'   // Large
-  | 'xl'   // Extra large
-  | 'xxl'; // Extra extra large
+<AtomicAvatar
+  source={{ uri: user.avatarUrl }}
+  name={user.name}
+/>
 ```
 
-## Best Practices
-
-### 1. Boyut Seçimi
-
+#### List Avatar
 ```tsx
-// Küçük alanlar için
-<AtomicAvatar size="xs" />
-
-// Liste elemanları için
-<AtomicAvatar size="sm" />
-
-// Normal kullanım
-<AtomicAvatar size="md" />
-
-// Vurgu için
-<AtomicAvatar size="lg" />
-
-// Profil sayfası için
-<AtomicAvatar size="xxl" />
+<FlatList
+  data={users}
+  renderItem={({ item }) => (
+    <ListItem>
+      <AtomicAvatar name={item.name} size="sm" />
+      <AtomicText>{item.name}</AtomicText>
+    </ListItem>
+  )}
+/>
 ```
 
-### 2. Initials Kullanımı
-
+#### Profile Header
 ```tsx
-// İsim varsa
-<AtomicAvatar name="Ahmet Yılmaz" /> {/* AY */}
-
-// İsim yoksa
-<AtomicAvatar /> {/* ? */}
+<View style={{ alignItems: 'center', padding: 24 }}>
+  <AtomicAvatar
+    source={{ uri: user.avatar }}
+    name={user.name}
+    size="xxl"
+  />
+  <AtomicText type="headlineLarge" marginTop="md">
+    {user.name}
+  </AtomicText>
+</View>
 ```
 
-### 3. Resim Yükleme
+## Props Reference
 
-```tsx
-// URI ile
-<AtomicAvatar source={{ uri: avatarUrl }} />
-
-// Local resim
-<AtomicAvatar source={require('./avatar.png')} />
-```
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `source` | `ImageSourcePropType` | No | - | Image source |
+| `name` | `string` | No* | - | User name (for initials) |
+| `size` | `AvatarSize` | No | `'md'` | Avatar size |
+| `customSize` | `number` | No | - | Custom size (px) |
+| `backgroundColor` | `string` | No | - | Background color |
+| `textColor` | `string` | No | - | Initials text color |
+| `borderRadius` | `number` | No | - | Corner radius |
+| `borderWidth` | `number` | No | `0` | Border width |
+| `borderColor` | `string` | No | - | Border color |
 
-## Erişilebilirlik
+*Either `source` or `name` should be provided
 
-AtomicAvatar, tam erişilebilirlik desteği sunar:
+## Accessibility
 
-- ✅ Screen reader desteği
-- ✅ Accessibility label
+- ✅ Screen reader announces user name
+- ✅ Accessibility label for image
 - ✅ Semantic role (image)
-- ✅ Test ID desteği
+- ✅ Test ID support
 
-## Performans İpuçları
+## Performance Tips
 
-1. **Image Caching**: Resimleri cache'leyin
-2. **Lazy Loading**: Uzun listelerde lazy load kullanın
-3. **Resize**: Resimleri doğru boyutta yükleyin
+1. **Image caching**: Cache avatar images
+2. **Lazy loading**: In long lists
+3. **Resize images**: Load appropriate size
+4. **Memoization**: Memo avatar in lists
 
-## İlgili Bileşenler
+## Related Components
 
-- [`AvatarGroup`](../../molecules/avatar/AvatarGroup/README.md) - Avatar grubu
-- [`AtomicCard`](./AtomicCard.README.md) - Kart bileşeni
-- [`AtomicIcon`](./AtomicIcon/README.md) - İkon bileşeni
+- [`AtomicText`](./AtomicText.README.md) - Text component
+- [`AtomicIcon`](./AtomicIcon.README.md) - Icon component
+- [`AtomicCard`](./AtomicCard.README.md) - Card component
 
-## Lisans
+## License
 
 MIT