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

package/src/molecules/listitem/README.md

@@ -1,498 +1,406 @@
 # ListItem
 
-ListItem is a versatile list item component with title, subtitle, and optional icons. Perfect for menus, settings, navigation lists, and more.
+A versatile list item component with title, subtitle, and optional icons for menus, settings, and navigation lists.
 
-## Features
+## Import & Usage
 
-- 📝 **Title & Subtitle**: Display primary and secondary text
-- 🎭 **Left Icon**: Icon on the left side
-- 🔄 **Right Icon**: Icon on the right side (for navigation)
-- 👆 **Pressable**: Optional press handler
-- ♿ **Accessible**: Full accessibility support
-- 🎨 **Theme-Aware**: Design token integration
-- ⚡ **Disabled State**: Disabled styling support
-
-## Installation
-
-```tsx
-import { ListItem } from 'react-native-design-system';
+```typescript
+import { ListItem } from 'react-native-design-system/src/molecules/listitem';
 ```
 
-## Basic Usage
-
-```tsx
-import React from 'react';
-import { View } from 'react-native';
-import { ListItem } from 'react-native-design-system';
-
-export const BasicExample = () => {
-  return (
-    <View>
-      <ListItem
-        title="Settings"
-        onPress={() => console.log('Settings pressed')}
-      />
-    </View>
-  );
-};
-```
+**Location:** `src/molecules/listitem/ListItem.tsx`
 
-## Basic Item
+## Basic Usage
 
 ```tsx
 <ListItem
-  title="Profile"
+  title="Settings"
+  subtitle="Configure your preferences"
+  leftIcon="settings-outline"
+  rightIcon="chevron-forward-outline"
+  onPress={() => navigateTo('Settings')}
 />
 ```
 
-## With Subtitle
+## Strategy
+
+**Purpose**: Provide a consistent, accessible list item component for navigation, settings, and content display.
+
+**When to Use**:
+- Navigation menus and drawers
+- Settings pages
+- User lists and contacts
+- File/item listings
+- Action menus (edit, share, delete)
+- Selection lists (radio buttons, checkboxes)
+
+**When NOT to Use**:
+- For card-based content (use AtomicCard instead)
+- For complex row layouts (use custom View instead)
+- For table data (use Table component instead)
+- For simple dividers (use Divider instead)
+
+## Rules
+
+### Required
+
+1. **MUST** have a `title` prop
+2. **ALWAYS** provide `onPress` when item is interactive
+3. **SHOULD** have descriptive icons (leftIcon for context, rightIcon for navigation)
+4. **MUST** have proper touch feedback when pressable
+5. **SHOULD** keep subtitles concise (1 line max recommended)
+6. **ALWAYS** use unique `key` props when rendering lists
+7. **MUST** respect disabled state (no feedback)
+
+### Icon Usage
+
+1. **Left icon**: Use for context/category (settings, profile, notifications)
+2. **Right icon**: Use for navigation indication (chevron, checkmark)
+3. **Consistency**: Use same icon style within list
+4. **Size**: Use appropriate icon size (md recommended)
+
+### Press Behavior
+
+1. **Must have onPress**: Always provide when using rightIcon for navigation
+2. **Visual feedback**: Show press effect
+3. **Disabled state**: No press effect when disabled
+4. **Action delay**: Add confirmation for destructive actions
+
+### Content Guidelines
+
+1. **Title**: Clear, concise (1-2 words recommended)
+2. **Subtitle**: Additional context, max 1 line
+3. **Truncation**: Titles should not wrap awkwardly
+4. **Grouping**: Use dividers or section headers for groups
+
+## Forbidden
+
+❌ **NEVER** do these:
 
 ```tsx
+// ❌ No title
 <ListItem
-  title="John Doe"
-  subtitle="Software Engineer"
+  // Missing title prop
+  subtitle="No title"
 />
-```
 
-## With Left Icon
-
-```tsx
+// ❌ Right icon without press handler
 <ListItem
   title="Settings"
-  leftIcon="settings-outline"
+  rightIcon="chevron-forward-outline" // ❌ Indicates navigation
+  // Missing onPress
 />
-```
 
-## Pressable with Right Icon
-
-```tsx
+// ❌ Generic icons
 <ListItem
-  title="Notifications"
-  rightIcon="chevron-forward-outline"
-  onPress={() => navigation.navigate('Notifications')}
+  title="Settings"
+  leftIcon="ellipse-outline" // ❌ Not descriptive
 />
-```
 
-## With Both Icons
+// ❌ Too long subtitle
+<ListItem
+  title="User"
+  subtitle="Lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor incididunt ut labore" // ❌ Too long
+/>
 
-```tsx
+// ❌ Destructive action without confirmation
 <ListItem
-  title="Dark Mode"
-  leftIcon="moon-outline"
-  rightIcon="chevron-forward-outline"
-  onPress={() => {}}
+  title="Delete Account"
+  leftIcon="trash-outline"
+  onPress={() => deleteAccount()} // ❌ No confirmation
 />
-```
 
-## Disabled Item
+// ❌ Missing keys in lists
+{items.map((item) => (
+  <ListItem
+    title={item.title} // ❌ No key prop
+  />
+))}
 
-```tsx
+// ❌ Disabled but pressable
 <ListItem
   title="Premium Feature"
-  subtitle="Upgrade to access"
-  leftIcon="diamond-outline"
   disabled
+  onPress={() => {}} // ❌ Should not have onPress when disabled
 />
 ```
 
-## Example Usages
-
-### Settings Menu
-
-```tsx
-export const SettingsMenu = () => {
-  const menuItems = [
-    {
-      title: 'Account',
-      subtitle: 'Personal information',
-      leftIcon: 'person-outline',
-      route: 'Account',
-    },
-    {
-      title: 'Notifications',
-      subtitle: 'Push notifications',
-      leftIcon: 'notifications-outline',
-      route: 'Notifications',
-    },
-    {
-      title: 'Privacy',
-      subtitle: 'Privacy settings',
-      leftIcon: 'shield-checkmark-outline',
-      route: 'Privacy',
-    },
-    {
-      title: 'Help',
-      subtitle: 'FAQ and support',
-      leftIcon: 'help-circle-outline',
-      route: 'Help',
-    },
-  ];
-
-  return (
-    <View>
-      {menuItems.map((item, index) => (
-        <ListItem
-          key={index}
-          title={item.title}
-          subtitle={item.subtitle}
-          leftIcon={item.leftIcon}
-          rightIcon="chevron-forward-outline"
-          onPress={() => navigation.navigate(item.route)}
-        />
-      ))}
-    </View>
-  );
-};
-```
-
-### User List
-
-```tsx
-export const UserList = ({ users }) => {
-  return (
-    <View>
-      {users.map((user) => (
-        <ListItem
-          key={user.id}
-          title={user.name}
-          subtitle={user.email}
-          leftIcon="person-outline"
-          onPress={() => navigation.navigate('UserProfile', { userId: user.id })}
-        />
-      ))}
-    </View>
-  );
-};
-```
+## Best Practices
 
-### Navigation Menu
+### Navigation Items
 
+✅ **DO**:
 ```tsx
-export const NavigationMenu = () => {
-  const menuItems = [
-    { title: 'Home', icon: 'home-outline', route: 'Home' },
-    { title: 'Search', icon: 'search-outline', route: 'Search' },
-    { title: 'Notifications', icon: 'notifications-outline', route: 'Notifications' },
-    { title: 'Messages', icon: 'chatbubble-outline', route: 'Messages' },
-    { title: 'Profile', icon: 'person-outline', route: 'Profile' },
-  ];
-
-  return (
-    <View>
-      {menuItems.map((item) => (
-        <ListItem
-          key={item.route}
-          title={item.title}
-          leftIcon={item.icon}
-          onPress={() => navigation.navigate(item.route)}
-        />
-      ))}
-    </View>
-  );
-};
+<ListItem
+  title="Settings"
+  leftIcon="settings-outline"
+  rightIcon="chevron-forward-outline"
+  onPress={() => navigation.navigate('Settings')}
+/>
 ```
 
-### Feature List
-
+❌ **DON'T**:
 ```tsx
-export const FeatureList = () => {
-  const features = [
-    {
-      title: 'Dark Mode',
-      subtitle: 'Reduce eye strain',
-      icon: 'moon-outline',
-      available: true,
-    },
-    {
-      title: 'Biometric Login',
-      subtitle: 'Face ID / Touch ID',
-      icon: 'finger-print-outline',
-      available: true,
-    },
-    {
-      title: 'Cloud Sync',
-      subtitle: 'Sync across devices',
-      icon: 'cloud-outline',
-      available: false,
-    },
-  ];
-
-  return (
-    <View>
-      {features.map((feature, index) => (
-        <ListItem
-          key={index}
-          title={feature.title}
-          subtitle={feature.subtitle}
-          leftIcon={feature.icon}
-          disabled={!feature.available}
-          onPress={feature.available ? () => enableFeature(feature) : undefined}
-          rightIcon={feature.available ? 'chevron-forward-outline' : undefined}
-        />
-      ))}
-    </View>
-  );
-};
+// ❌ Navigation indicator without action
+<ListItem
+  title="Settings"
+  rightIcon="chevron-forward-outline"
+  // Missing onPress
+/>
 ```
 
-### Action Menu
+### Icon Selection
 
+✅ **DO**:
 ```tsx
-export const ActionMenu = ({ onAction }) => {
-  const actions = [
-    { title: 'Edit', icon: 'create-outline', action: 'edit' },
-    { title: 'Share', icon: 'share-outline', action: 'share' },
-    { title: 'Delete', icon: 'trash-outline', action: 'delete' },
-  ];
-
-  return (
-    <View>
-      {actions.map((action) => (
-        <ListItem
-          key={action.action}
-          title={action.title}
-          leftIcon={action.icon}
-          onPress={() => onAction(action.action)}
-          rightIcon="chevron-forward-outline"
-        />
-      ))}
-    </View>
-  );
-};
+// Descriptive icons
+<ListItem
+  title="Notifications"
+  leftIcon="notifications-outline"
+/>
+<ListItem
+  title="Profile"
+  leftIcon="person-outline"
+/>
 ```
 
-### Contact List
-
+❌ **DON'T**:
 ```tsx
-export const ContactList = ({ contacts }) => {
-  return (
-    <View>
-      {contacts.map((contact) => (
-        <ListItem
-          key={contact.id}
-          title={contact.name}
-          subtitle={contact.phone}
-          leftIcon="person-outline"
-          rightIcon="call-outline"
-          onPress={() => Linking.openURL(`tel:${contact.phone}`)}
-        />
-      ))}
-    </View>
-  );
-};
+// Generic icons
+<ListItem
+  title="Notifications"
+  leftIcon="ellipse-outline" // ❌ Not descriptive
+/>
 ```
 
-### File List
+### List Rendering
 
+✅ **DO**:
 ```tsx
-export const FileList = ({ files }) => {
-  const getFileIcon = (fileName) => {
-    if (fileName.endsWith('.pdf')) return 'document-text-outline';
-    if (fileName.endsWith('.jpg') || fileName.endsWith('.png')) return 'image-outline';
-    if (fileName.endsWith('.mp4')) return 'videocam-outline';
-    return 'document-outline';
-  };
-
-  return (
-    <View>
-      {files.map((file) => (
-        <ListItem
-          key={file.id}
-          title={file.name}
-          subtitle={`${file.size} • ${file.date}`}
-          leftIcon={getFileIcon(file.name)}
-          onPress={() => openFile(file)}
-          rightIcon="ellipsis-vertical-outline"
-        />
-      ))}
-    </View>
-  );
-};
+{users.map((user) => (
+  <ListItem
+    key={user.id} // ✅ Unique key
+    title={user.name}
+    subtitle={user.email}
+    onPress={() => navigateToUser(user.id)}
+  />
+))}
 ```
 
-### Download List
-
+❌ **DON'T**:
 ```tsx
-export const DownloadList = ({ downloads }) => {
-  return (
-    <View>
-      {downloads.map((download) => (
-        <ListItem
-          key={download.id}
-          title={download.fileName}
-          subtitle={`${download.progress}% • ${download.status}`}
-          leftIcon="download-outline"
-          disabled={download.status === 'downloading'}
-          onPress={() => {
-            if (download.status === 'completed') {
-              openDownload(download);
-            } else if (download.status === 'pending') {
-              startDownload(download);
-            }
-          }}
-          rightIcon={download.status === 'completed' ? 'checkmark-circle' : undefined}
-        />
-      ))}
-    </View>
-  );
-};
+{users.map((user, index) => (
+  <ListItem
+    key={index} // ❌ Index as key
+    title={user.name}
+  />
+))}
 ```
 
-### Selection List
+### Destructive Actions
 
+✅ **DO**:
 ```tsx
-export const SelectionList = ({ options, selectedOption, onSelect }) => {
-  return (
-    <View>
-      {options.map((option) => (
-        <ListItem
-          key={option.id}
-          title={option.title}
-          subtitle={option.subtitle}
-          leftIcon={option.icon}
-          onPress={() => onSelect(option)}
-          rightIcon={selectedOption?.id === option.id ? 'checkmark' : undefined}
-        />
-      ))}
-    </View>
-  );
-};
+<ListItem
+  title="Delete Account"
+  leftIcon="trash-outline"
+  onPress={() => {
+    showConfirmation({
+      title: 'Delete Account',
+      message: 'This action cannot be undone',
+      onConfirm: deleteAccount,
+    });
+  }}
+/>
 ```
 
-### Grouped List
-
+❌ **DON'T**:
 ```tsx
-export const GroupedList = () => {
-  const groups = [
-    {
-      title: 'Account',
-      items: [
-        { title: 'Profile', icon: 'person-outline' },
-        { title: 'Security', icon: 'shield-outline' },
-      ],
-    },
-    {
-      title: 'Preferences',
-      items: [
-        { title: 'Appearance', icon: 'color-palette-outline' },
-        { title: 'Language', icon: 'globe-outline' },
-      ],
-    },
-  ];
-
-  return (
-    <View>
-      {groups.map((group, groupIndex) => (
-        <View key={groupIndex}>
-          <AtomicText
-            type="labelLarge"
-            color="primary"
-            style={{ paddingHorizontal: 16, paddingVertical: 8 }}
-          >
-            {group.title}
-          </AtomicText>
-
-          {group.items.map((item, itemIndex) => (
-            <ListItem
-              key={itemIndex}
-              title={item.title}
-              leftIcon={item.icon}
-              onPress={() => handleNavigation(item.title)}
-              rightIcon="chevron-forward-outline"
-            />
-          ))}
-        </View>
-      ))}
-    </View>
-  );
-};
+<ListItem
+  title="Delete Account"
+  leftIcon="trash-outline"
+  onPress={() => deleteAccount()} // ❌ No confirmation
+/>
 ```
 
-## Props
-
-### ListItemProps
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `title` | `string` | - **(Required)** | Primary text |
-| `subtitle` | `string` | - | Secondary text |
-| `leftIcon` | `string` | - | Left icon name (Ionicons) |
-| `rightIcon` | `string` | - | Right icon name (Ionicons) |
-| `onPress` | `() => void` | - | Press callback (makes item pressable) |
-| `disabled` | `boolean` | `false` | Disable the item |
-| `style` | `ViewStyle` | - | Custom container style |
-
-## Best Practices
-
-### 1. Icon Selection
-
+## AI Coding Guidelines
+
+### For AI Agents
+
+When generating ListItem components, follow these rules:
+
+1. **Always import from correct path**:
+   ```typescript
+   import { ListItem } from 'react-native-design-system/src/molecules/listitem';
+   ```
+
+2. **Always provide a title**:
+   ```tsx
+   // ✅ Good
+   <ListItem
+     title="Settings"
+     onPress={handlePress}
+   />
+
+   // ❌ Bad - no title
+   <ListItem
+     onPress={handlePress}
+   />
+   ```
+
+3. **Always match icons with context**:
+   ```tsx
+   // ✅ Good - descriptive icons
+   const iconMap = {
+     settings: 'settings-outline',
+     profile: 'person-outline',
+     notifications: 'notifications-outline',
+     privacy: 'shield-checkmark-outline',
+   };
+
+   // ❌ Bad - generic icons
+   const icons = ['ellipse-outline', 'circle-outline'];
+   ```
+
+4. **Always use unique keys in lists**:
+   ```tsx
+   // ✅ Good - unique ID as key
+   {items.map((item) => (
+     <ListItem
+       key={item.id}
+       title={item.title}
+       onPress={() => handleItem(item)}
+     />
+   ))}
+
+   // ❌ Bad - index as key
+   {items.map((item, index) => (
+     <ListItem
+       key={index}
+       title={item.title}
+     />
+   ))}
+   ```
+
+5. **Always add confirmation for destructive actions**:
+   ```tsx
+   // ✅ Good - confirmation dialog
+   <ListItem
+     title="Delete"
+     leftIcon="trash-outline"
+     onPress={() => {
+       Alert.alert(
+         'Confirm Delete',
+         'This action cannot be undone',
+         [
+           { text: 'Cancel', style: 'cancel' },
+           { text: 'Delete', style: 'destructive', onPress: handleDelete },
+         ]
+       );
+     }}
+   />
+
+   // ❌ Bad - immediate action
+   <ListItem
+     title="Delete"
+     leftIcon="trash-outline"
+     onPress={handleDelete} // No confirmation
+   />
+   ```
+
+### Common Patterns
+
+#### Settings Menu Item
 ```tsx
-// ✅ Good: Descriptive icons
 <ListItem
   title="Settings"
   leftIcon="settings-outline"
-/>
-
-// ❌ Bad: Generic icons
-<ListItem
-  title="Settings"
-  leftIcon="ellipse-outline"
+  rightIcon="chevron-forward-outline"
+  onPress={() => navigation.navigate('Settings')}
 />
 ```
 
-### 2. Right Icon Usage
+#### User List Item
+```tsx
+{users.map((user) => (
+  <ListItem
+    key={user.id}
+    title={user.name}
+    subtitle={user.email}
+    leftIcon="person-outline"
+    onPress={() => navigation.navigate('UserProfile', { userId: user.id })}
+  />
+))}
+```
 
+#### Selection List Item
 ```tsx
-// ✅ Good: Navigation indicator
-<ListItem
-  title="Settings"
-  rightIcon="chevron-forward-outline"
-  onPress={() => navigate('Settings')}
-/>
+{options.map((option) => (
+  <ListItem
+    key={option.id}
+    title={option.title}
+    leftIcon={option.icon}
+    rightIcon={selectedId === option.id ? 'checkmark' : undefined}
+    onPress={() => setSelectedId(option.id)}
+  />
+))}
+```
 
-// ❌ Bad: No press handler
+#### Action Menu Item
+```tsx
 <ListItem
-  title="Settings"
+  title="Edit"
+  leftIcon="create-outline"
   rightIcon="chevron-forward-outline"
+  onPress={() => onAction('edit')}
 />
 ```
 
-### 3. Subtitle Length
-
+#### Contact Item
 ```tsx
-// ✅ Good: Concise
 <ListItem
-  subtitle="Software Engineer at Google"
-/>
-
-// ❌ Bad: Too long
-<ListItem
-  subtitle="Lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
+  title={contact.name}
+  subtitle={contact.phone}
+  leftIcon="person-outline"
+  rightIcon="call-outline"
+  onPress={() => Linking.openURL(`tel:${contact.phone}`)}
 />
 ```
 
-## Accessibility
+## Props Reference
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `title` | `string` | Yes | - | Primary text |
+| `subtitle` | `string` | No | - | Secondary text |
+| `leftIcon` | `string` | No | - | Left icon name (Ionicons) |
+| `rightIcon` | `string` | No | - | Right icon name (Ionicons) |
+| `onPress` | `() => void` | No | - | Press callback |
+| `disabled` | `boolean` | No | `false` | Disable the item |
+| `style` | `ViewStyle` | No | - | Custom container style |
 
-ListItem provides full accessibility support:
+## Accessibility
 
-- ✅ Screen reader support
-- ✅ Touch target size
-- ✅ Accessibility labels
-- ✅ Disabled state announcements
-- ✅ Semantic roles
+- ✅ Screen reader announces title and subtitle
+- ✅ Touch target size maintained (min 44x44pt)
+- ✅ Press feedback for screen readers
+- ✅ Disabled state announced
+- ✅ Semantic list item role
+- ✅ Icon accessibility labels
 
 ## Performance Tips
 
-1. **Memoization**: Memo list items for large lists
-2. **Key Prop**: Always use unique keys
-3. **Optimization**: Use `removeClippedSubviews` for long lists
+1. **Memoization**: Memo ListItem components for large lists
+2. **Unique keys**: Always use unique IDs as keys (not index)
+3. **Avoid inline functions**: Use useCallback for onPress handlers
+4. **FlatList**: Use FlatList for long lists instead of map
 
 ## Related Components
 
 - [`List`](../List/README.md) - List container component
 - [`Avatar`](../avatar/README.md) - User avatar component
-- [`AtomicIcon`](../../atoms/AtomicIcon/README.md) - Icon component
 - [`Divider`](../Divider/README.md) - List divider component
+- [`AtomicIcon`](../../atoms/AtomicIcon/README.md) - Icon component
 
 ## License