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

package/src/molecules/List/README.md

@@ -1,568 +1,361 @@
 # List
 
-List, FlatList wrapper'ı olan responsive bir liste bileşenidir. Pull-to-refresh desteği, içerik padding'i ve theme-aware renkler sunar.
+List is a responsive FlatList wrapper component with pull-to-refresh support, content padding, and theme-aware colors.
 
-## Özellikler
+## Import & Usage
 
-- 📜 **FlatList Wrapper**: React Native FlatList'in tüm özellikleri
-- 🔄 **Pull-to-Refresh**: Yenileme desteği
-- 📏 **Content Padding**: Responsive içerik padding'i
-- 🎨 **Theme-Aware**: Design token uyumlu
-- ⚡ **Performanslı**: Optimize edilmiş liste performansı
-- ♿ **Erişilebilir**: Tam erişilebilirlik desteği
-
-## Kurulum
-
-```tsx
-import { List } from 'react-native-design-system';
+```typescript
+import { List } from 'react-native-design-system/src/molecules/List';
 ```
 
-## Temel Kullanım
+**Location:** `src/molecules/List/List.tsx`
 
-```tsx
-import React from 'react';
-import { View } from 'react-native';
-import { List } from 'react-native-design-system';
-
-export const BasicExample = () => {
-  const data = [
-    { id: '1', title: 'Öğe 1' },
-    { id: '2', title: 'Öğe 2' },
-    { id: '3', title: 'Öğe 3' },
-  ];
-
-  return (
-    <List
-      data={data}
-      renderItem={({ item }) => (
-        <View style={{ padding: 16 }}>
-          <AtomicText>{item.title}</AtomicText>
-        </View>
-      )}
-      keyExtractor={(item) => item.id}
-    />
-  );
-};
-```
-
-## Basit Liste
+## Basic Usage
 
 ```tsx
-const users = [
-  { id: '1', name: 'Ahmet Yılmaz' },
-  { id: '2', name: 'Ayşe Demir' },
-  { id: '3', name: 'Mehmet Kaya' },
-];
-
 <List
-  data={users}
-  renderItem={({ item }) => (
-    <ListItem title={item.name} />
-  )}
+  data={items}
+  renderItem={({ item }) => <ItemCard item={item} />}
   keyExtractor={(item) => item.id}
 />
 ```
 
-## Pull-to-Refresh
+## Strategy
 
-```tsx
-export const RefreshableList = () => {
-  const [data, setData] = useState([]);
-  const [refreshing, setRefreshing] = useState(false);
-
-  const onRefresh = async () => {
-    setRefreshing(true);
-    const newData = await fetchData();
-    setData(newData);
-    setRefreshing(false);
-  };
-
-  return (
-    <List
-      data={data}
-      renderItem={({ item }) => <ItemCard item={item} />}
-      keyExtractor={(item) => item.id}
-      onRefresh={onRefresh}
-      refreshing={refreshing}
-    />
-  );
-};
-```
+**Purpose**: Provide a performant, theme-aware list component that wraps React Native's FlatList with sensible defaults.
+
+**When to Use**:
+- Displaying scrolling lists of data
+- Rendering large datasets efficiently
+- Implementing pull-to-refresh functionality
+- Creating infinite scroll lists
+
+**When NOT to Use**:
+- For small static lists - use ScrollView or map
+- For simple layouts - use FlatList directly
+- For grid layouts - use FlatList with numColumns
 
-## Content Padding
+## Rules
+
+### Required
+
+1. **ALWAYS** provide `data` array
+2. **MUST** provide `renderItem` function
+3. **ALWAYS** provide `keyExtractor` function
+4. **NEVER** use array index as key
+5. **MUST** handle empty state
+
+### Performance
+
+1. **ALWAYS** use stable keys from data
+2. **MUST** memoize renderItem with useCallback
+3. **SHOULD** use `getItemLayout` for fixed-size items
+4. **NEVER** inline renderItem function
+
+### Key Extraction
+
+1. **ALWAYS** use unique IDs from data
+2. **NEVER** use array index as key
+3. **MUST** be stable across re-renders
+4. **SHOULD** be unique across all items
+
+## Forbidden
+
+❌ **NEVER** do these:
 
 ```tsx
+// ❌ Missing required props
+<List /> {/* Missing data, renderItem, keyExtractor */}
+
+// ❌ Using index as key
 <List
   data={items}
   renderItem={({ item }) => <ItemCard item={item} />}
+  keyExtractor={(item, index) => index.toString()} // ❌ Bad
+/>
+
+// ❌ Inline renderItem
+<List
+  data={items}
+  renderItem={({ item }) => ( // ❌ Not memoized
+    <ItemCard item={item} />
+  )}
   keyExtractor={(item) => item.id}
-  contentPadding
 />
-```
 
-## Örnek Kullanımlar
+// ❌ No keyExtractor
+<List
+  data={items}
+  renderItem={({ item }) => <ItemCard item={item} />}
+  // Missing keyExtractor ❌
+/>
 
-### Kullanıcı Listesi
+// ❌ No empty state
+<List
+  data={[]} // Empty but no empty state shown
+  renderItem={renderItem}
+  keyExtractor={keyExtractor}
+/>
 
-```tsx
-export const UserList = () => {
-  const [users, setUsers] = useState([]);
-
-  useEffect(() => {
-    fetchUsers().then(setUsers);
-  }, []);
-
-  const renderUser = ({ item }) => (
-    <ListItem
-      title={item.name}
-      subtitle={item.email}
-      left={() => (
-        <Avatar
-          uri={item.avatar}
-          name={item.name}
-          size="md"
-        />
-      )}
-      onPress={() => navigation.navigate('UserProfile', { userId: item.id })}
-    />
-  );
-
-  return (
-    <List
-      data={users}
-      renderItem={renderUser}
-      keyExtractor={(item) => item.id}
-      contentPadding
-    />
-  );
-};
+// ❌ Wrong data type
+<List
+  data="not an array" // ❌ Should be array
+  renderItem={renderItem}
+  keyExtractor={keyExtractor}
+/>
 ```
 
-### Sonsuz Kaydırma
+## Best Practices
+
+### Key Extraction
 
+✅ **DO**:
 ```tsx
-export const InfiniteList = () => {
-  const [data, setData] = useState([]);
-  const [loading, setLoading] = useState(false);
-  const [page, setPage] = useState(1);
-
-  const loadMore = async () => {
-    if (loading) return;
-    setLoading(true);
-    const newData = await fetchItems(page);
-    setData([...data, ...newData]);
-    setPage(page + 1);
-    setLoading(false);
-  };
-
-  const renderFooter = () => {
-    if (!loading) return null;
-    return (
-      <View style={{ padding: 16 }}>
-        <AtomicSpinner size="md" />
-      </View>
-    );
-  };
-
-  return (
-    <List
-      data={data}
-      renderItem={({ item }) => <ItemCard item={item} />}
-      keyExtractor={(item) => item.id}
-      onEndReached={loadMore}
-      onEndReachedThreshold={0.5}
-      ListFooterComponent={renderFooter}
-      contentPadding
-    />
-  );
-};
-```
+// Use unique ID
+keyExtractor={(item) => item.id}
 
-### Ürün Listesi
+// Use composite key
+keyExtractor={(item) => `${item.type}-${item.id}`}
 
-```tsx
-export const ProductList = () => {
-  const [products, setProducts] = useState([]);
-  const [refreshing, setRefreshing] = useState(false);
-
-  const onRefresh = async () => {
-    setRefreshing(true);
-    const data = await fetchProducts();
-    setProducts(data);
-    setRefreshing(false);
-  };
-
-  const renderProduct = ({ item }) => (
-    <MediaCard
-      uri={item.image}
-      title={item.name}
-      subtitle={`${item.price} TL`}
-      onPress={() => navigation.navigate('ProductDetail', { productId: item.id })}
-    />
-  );
-
-  return (
-    <List
-      data={products}
-      renderItem={renderProduct}
-      keyExtractor={(item) => item.id}
-      onRefresh={onRefresh}
-      refreshing={refreshing}
-      numColumns={2}
-      columnWrapperStyle={{ gap: 8 }}
-      contentPadding
-    />
-  );
-};
+// Use slug/UUID
+keyExtractor={(item) => item.slug}
 ```
 
-### Haber Listesi
-
+❌ **DON'T**:
 ```tsx
-export const NewsList = () => {
-  const [articles, setArticles] = useState([]);
-
-  const renderArticle = ({ item }) => (
-    <AtomicCard
-      variant="outlined"
-      style={{ marginBottom: 16 }}
-      onPress={() => navigation.navigate('Article', { articleId: item.id })}
-    >
-      <View style={{ padding: 16 }}>
-        <AtomicText type="titleMedium" style={{ marginBottom: 8 }}>
-          {item.title}
-        </AtomicText>
-        <AtomicText type="bodyMedium" color="secondary" numberOfLines={2}>
-          {item.excerpt}
-        </AtomicText>
-        <View style={{ flexDirection: 'row', marginTop: 8 }}>
-          <AtomicText type="labelSmall" color="tertiary">
-            {item.category}
-          </AtomicText>
-          <AtomicText type="labelSmall" color="tertiary" style={{ marginLeft: 16 }}>
-            {formatDate(item.publishedAt)}
-          </AtomicText>
-        </View>
-      </View>
-    </AtomicCard>
-  );
-
-  return (
-    <List
-      data={articles}
-      renderItem={renderArticle}
-      keyExtractor={(item) => item.id}
-      contentPadding
-    />
-  );
-};
+// Don't use index
+keyExtractor={(item, index) => index.toString()} // ❌
+
+// Don't use mutable values
+keyExtractor={(item) => item.name} // May change ❌
 ```
 
-### Sohbet Listesi
+### Performance
 
+✅ **DO**:
 ```tsx
-export const ChatList = () => {
-  const [conversations, setConversations] = useState([]);
-
-  const renderConversation = ({ item }) => (
-    <Pressable
-      style={{ flexDirection: 'row', alignItems: 'center', padding: 16 }}
-      onPress={() => navigation.navigate('Chat', { chatId: item.id })}
-    >
-      <Avatar
-        uri={item.avatar}
-        name={item.name}
-        showStatus
-        status={item.online ? 'online' : 'offline'}
-        size="md"
-      />
-
-      <View style={{ flex: 1, marginLeft: 12 }}>
-        <View style={{ flexDirection: 'row', justifyContent: 'space-between' }}>
-          <AtomicText type="bodyLarge" fontWeight="600">
-            {item.name}
-          </AtomicText>
-          <AtomicText type="bodySmall" color="tertiary">
-            {formatTime(item.lastMessageAt)}
-          </AtomicText>
-        </View>
-
-        <AtomicText
-          type="bodyMedium"
-          color="secondary"
-          numberOfLines={1}
-          style={{ marginTop: 4 }}
-        >
-          {item.lastMessage}
-        </AtomicText>
-      </View>
-    </Pressable>
-  );
-
-  return (
-    <List
-      data={conversations}
-      renderItem={renderConversation}
-      keyExtractor={(item) => item.id}
-      contentPadding
-    />
-  );
-};
-```
+// Memoize renderItem
+const renderItem = useCallback(({ item }) => (
+  <ItemCard item={item} />
+), []);
 
-### Arama Sonuçları
+// Use getItemLayout for fixed sizes
+getItemLayout={(data, index) => ({
+  length: ITEM_HEIGHT,
+  offset: ITEM_HEIGHT * index,
+  index,
+})}
+```
 
+❌ **DON'T**:
 ```tsx
-export const SearchResults = ({ query }) => {
-  const [results, setResults] = useState([]);
-  const [loading, setLoading] = useState(false);
-
-  useEffect(() => {
-    const search = async () => {
-      setLoading(true);
-      const data = await searchItems(query);
-      setResults(data);
-      setLoading(false);
-    };
-
-    if (query.length > 2) {
-      search();
-    }
-  }, [query]);
-
-  const renderResult = ({ item }) => (
-    <ListItem
-      title={item.title}
-      subtitle={item.description}
-      left={() => <AtomicIcon name="search-outline" size="md" />}
-      onPress={() => navigation.navigate('Detail', { id: item.id })}
-    />
-  );
-
-  if (loading) {
-    return <AtomicSpinner fullContainer />;
-  }
-
-  if (results.length === 0) {
-    return (
-      <EmptyState
-        icon="search-outline"
-        title="Sonuç bulunamadı"
-        message={`"${query}" için sonuç bulunamadı`}
-      />
-    );
-  }
-
-  return (
-    <List
-      data={results}
-      renderItem={renderResult}
-      keyExtractor={(item) => item.id}
-      contentPadding
-    />
-  );
-};
+// Don't create functions in render
+<List
+  renderItem={({ item }) => <ItemCard item={item} />} // ❌ New function each render
+/>
 ```
 
-### Bildirim Listesi
+### Content Padding
 
+✅ **DO**:
 ```tsx
-export const NotificationList = () => {
-  const [notifications, setNotifications] = useState([]);
-
-  const renderNotification = ({ item }) => (
-    <View
-      style={{
-        flexDirection: 'row',
-        padding: 16,
-        backgroundColor: item.read ? 'transparent' : `${tokens.colors.primary}10`,
-        borderBottomWidth: 1,
-        borderBottomColor: tokens.colors.border,
-      }}
-    >
-      <View style={{ marginRight: 12 }}>
-        <AtomicIcon
-          name={item.type === 'success' ? 'checkmark-circle' : 'information-circle'}
-          size="lg"
-          color={item.type === 'success' ? 'success' : 'primary'}
-        />
-      </View>
-
-      <View style={{ flex: 1 }}>
-        <AtomicText type="bodyLarge" fontWeight="600">
-          {item.title}
-        </AtomicText>
-        <AtomicText type="bodyMedium" color="secondary" style={{ marginTop: 4 }}>
-          {item.message}
-        </AtomicText>
-        <AtomicText type="labelSmall" color="tertiary" style={{ marginTop: 8 }}>
-          {formatRelativeTime(item.createdAt)}
-        </AtomicText>
-      </View>
-    </View>
-  );
-
-  return (
-    <List
-      data={notifications}
-      renderItem={renderNotification}
-      keyExtractor={(item) => item.id}
-      contentPadding
-    />
-  );
-};
-```
+// Use built-in contentPadding
+<List contentPadding />
 
-### Görev Listesi
+// Manual padding for custom layouts
+<List
+  contentContainerStyle={{ padding: 16 }}
+/>
+```
 
+❌ **DON'T**:
 ```tsx
-export const TaskList = () => {
-  const [tasks, setTasks] = useState([]);
-
-  const toggleTask = (taskId) => {
-    setTasks(tasks.map(task =>
-      task.id === taskId ? { ...task, completed: !task.completed } : task
-    ));
-  };
-
-  const renderTask = ({ item }) => (
-    <View
-      style={{
-        flexDirection: 'row',
-        alignItems: 'center',
-        padding: 16,
-        borderBottomWidth: 1,
-        borderBottomColor: tokens.colors.border,
-      }}
-    >
-      <Pressable onPress={() => toggleTask(item.id)}>
-        <AtomicIcon
-          name={item.completed ? 'checkmark-circle' : 'ellipse-outline'}
-          size="md"
-          color={item.completed ? 'success' : 'secondary'}
-        />
-      </Pressable>
-
-      <View style={{ flex: 1, marginLeft: 12 }}>
-        <AtomicText
-          type="bodyLarge"
-          style={{
-            textDecorationLine: item.completed ? 'line-through' : 'none',
-            opacity: item.completed ? 0.6 : 1,
-          }}
-        >
-          {item.title}
-        </AtomicText>
-
-        {item.dueDate && (
-          <AtomicText type="labelSmall" color="tertiary" style={{ marginTop: 4 }}>
-            {formatDate(item.dueDate)}
-          </AtomicText>
-        )}
-      </View>
-
-      {item.priority === 'high' && (
-        <AtomicIcon name="alert-circle" size="sm" color="error" />
-      )}
-    </View>
-  );
-
-  return (
-    <List
-      data={tasks}
-      renderItem={renderTask}
-      keyExtractor={(item) => item.id}
-      contentPadding
-    />
-  );
-};
+// Don't add unnecessary wrapper
+<View style={{ padding: 16 }}>
+  <List /> {/* Extra wrapper ❌ */}
+</View>
 ```
 
-## Props
-
-### ListProps
-
-| Prop | Tip | Varsayılan | Açıklama |
-|------|-----|------------|----------|
-| `data` | `T[]` | - **(Zorunlu)** | Liste verisi |
-| `renderItem` | `ListRenderItem<T>` | - **(Zorunlu)** | Render fonksiyonu |
-| `keyExtractor` | `(item, index) => string` | - **(Zorunlu)** | Key extractor |
-| `onRefresh` | `() => void` | - | Yenileme callback'i |
-| `refreshing` | `boolean` | `false` | Yeneleniyor durumunda |
-| `contentPadding` | `boolean` | `false` | İçerik padding'i |
-
-**Not:** List, FlatList'in tüm props'larını destekler.
-
-## Best Practices
-
-### 1. Key Extractor
+### Empty State
 
+✅ **DO**:
 ```tsx
-// ✅ İyi - Unique ve stable
-keyExtractor={(item) => item.id}
-
-// ❌ Kötü - Index kullanımı
-keyExtractor={(item, index) => index.toString()}
+{data.length === 0 ? (
+  <EmptyState
+    icon="inbox-outline"
+    title="No items"
+    message="Get started by adding your first item"
+  />
+) : (
+  <List data={data} />
+)}
 ```
 
-### 2. Performans
+❌ **DON'T**:
+```tsx
+// Don't show empty list
+<List data={[]} /> {/* Shows nothing ❌ */}
+```
 
+## AI Coding Guidelines
+
+### For AI Agents
+
+When generating List components, follow these rules:
+
+1. **Always import from correct path**:
+   ```typescript
+   import { List } from 'react-native-design-system/src/molecules/List';
+   ```
+
+2. **Always provide required props**:
+   ```tsx
+   <List
+     data={dataArray}
+     renderItem={renderItemFunction}
+     keyExtractor={keyExtractorFunction}
+   />
+   ```
+
+3. **Always use unique keys**:
+   ```tsx
+   // ✅ Good
+   keyExtractor={(item) => item.id}
+
+   // ❌ Bad
+   keyExtractor={(item, index) => index.toString()}
+   ```
+
+4. **Always memoize renderItem**:
+   ```tsx
+   const renderItem = useCallback(({ item }) => (
+     <ItemCard item={item} />
+   ), []);
+   ```
+
+5. **Never use inline functions**:
+   ```tsx
+   // ❌ Bad
+   <List
+     renderItem={({ item }) => <ItemCard item={item} />}
+   />
+
+   // ✅ Good
+   const renderItem = useCallback(({ item }) => (
+     <ItemCard item={item} />
+   ), []);
+   <List renderItem={renderItem} />
+   ```
+
+### Common Patterns
+
+#### Basic List
 ```tsx
-// ✅ Memo kullan
 const renderItem = useCallback(({ item }) => (
-  <ItemCard item={item} />
+  <ListItem
+    title={item.title}
+    onPress={() => navigateToDetail(item.id)}
+  />
 ), []);
 
-// ✅ Inline function değil
-renderItem={renderItem}
+<List
+  data={items}
+  renderItem={renderItem}
+  keyExtractor={(item) => item.id}
+  contentPadding
+/>
 ```
 
-### 3. Content Padding
-
+#### Pull-to-Refresh
 ```tsx
-// Liste için
-<List contentPadding />
+const [refreshing, setRefreshing] = useState(false);
 
-// Manuel padding
-<View style={{ padding: 16 }}>
-  <List />
-</View> // ❌ Gereksiz
+const onRefresh = useCallback(async () => {
+  setRefreshing(true);
+  await loadData();
+  setRefreshing(false);
+}, []);
+
+<List
+  data={items}
+  renderItem={renderItem}
+  keyExtractor={(item) => item.id}
+  onRefresh={onRefresh}
+  refreshing={refreshing}
+/>
 ```
 
-### 4. Empty State
+#### Infinite Scroll
+```tsx
+const [loading, setLoading] = useState(false);
+
+const loadMore = useCallback(async () => {
+  if (loading) return;
+  setLoading(true);
+  const newItems = await fetchMore();
+  setItems([...items, ...newItems]);
+  setLoading(false);
+}, [loading, items]);
+
+<List
+  data={items}
+  renderItem={renderItem}
+  keyExtractor={(item) => item.id}
+  onEndReached={loadMore}
+  onEndReachedThreshold={0.5}
+  ListFooterComponent={loading ? <LoadingSpinner /> : null}
+/>
+```
 
+#### Grid Layout
 ```tsx
-{data.length === 0 ? (
-  <EmptyState />
-) : (
-  <List data={data} />
-)}
+<List
+  data={items}
+  renderItem={renderItem}
+  keyExtractor={(item) => item.id}
+  numColumns={2}
+  columnWrapperStyle={{ gap: 8 }}
+  contentPadding
+/>
 ```
 
-## Erişilebilirlik
+## Props Reference
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `data` | `T[]` | Yes | - | List data array |
+| `renderItem` | `ListRenderItem<T>` | Yes | - | Render function |
+| `keyExtractor` | `(item, index) => string` | Yes | - | Key extractor |
+| `onRefresh` | `() => void` | No | - | Refresh callback |
+| `refreshing` | `boolean` | No | `false` | Refreshing state |
+| `contentPadding` | `boolean` | No | `false` | Add content padding |
+
+**Note:** List supports all FlatList props.
 
-List, tam erişilebilirlik desteği sunar:
+## Accessibility
 
-- ✅ Screen reader desteği
-- ✅ Semantic list anlamları
-- ✅ Focus management
-- ✅ Keyboard navigation
+- ✅ Screen reader announces list items
+- ✅ Semantic list structure
+- ✅ Focus management for keyboard navigation
+- ✅ Accessibility labels supported
+- ✅ Proper list semantics
 
-## Performans İpuçları
+## Performance
 
-1. **keyExtractor**: Her item için unique key kullanın
-2. **Memoization**: renderItem fonksiyonunu memo edin
-3. **removeClippedSubviews**: Büyük listelerde kullanın
-4. **getItemLayout**: Sabit boyutlu item'larda kullanın
-5. **windowSize**: Viewport dışındaki item sayısını sınırlayın
+1. **Key extraction**: Use unique, stable keys
+2. **Memoization**: Memo renderItem function
+3. **Windowing**: Uses FlatList windowing
+4. **Optimization**: Consider `removeClippedSubviews` for large lists
+5. **Layout**: Use `getItemLayout` for fixed-size items
+6. **Batching**: Batch updates to data
 
-## İlgili Bileşenler
+## Related Components
 
 - [`FlatList`](https://reactnative.dev/docs/flatlist) - React Native FlatList
-- [`ListItem`](../listitem/README.md) - Liste öğesi
-- [`MediaCard`](../media-card/README.md) - Medya kartı
-- [`Avatar`](../avatar/README.md) - Avatar bileşeni
+- [`ListItem`](../listitem/README.md) - List item component
+- [`MediaCard`](../media-card/README.md) - Media card component
+- [`Avatar`](../avatar/README.md) - Avatar component
 
-## Lisans
+## License
 
 MIT