@delightui/components 0.1.105 → 0.1.107

package/docs/components/atoms/ListItem.md

@@ -0,0 +1,502 @@
+# ListItem
+
+A versatile list item component that provides a standardized way to display individual items within lists. It supports leading and trailing icons, click interactions, and disabled states, making it ideal for navigation menus, option lists, and interactive collections.
+
+## Aliases
+
+- ListItem
+- ListElement
+- Item
+
+## Props Breakdown
+
+**Extends:** `HTMLAttributes<HTMLDivElement>` (excluding 'style')
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `leadingIcon` | `ReactNode` | `undefined` | No | Icon to be displayed before the content |
+| `trailingIcon` | `ReactNode` | `undefined` | No | Icon to be displayed after the content |
+| `disabled` | `boolean` | `false` | No | Whether the list item is disabled |
+| `onClick` | `(event?: MouseEvent<HTMLElement>) => void` | `undefined` | No | Click event handler for the list item |
+| `children` | `ReactNode` | `undefined` | No | The content of the list item |
+| `className` | `string` | `undefined` | No | Additional class for styling |
+
+*Note: In addition to the props listed above, this component inherits all HTML div attributes (except 'style') such as `id`, `data-*`, `aria-*`, `onMouseEnter`, `onMouseLeave`, etc., providing full accessibility and interaction support.*
+
+## Examples
+
+### Basic List Item
+
+```tsx
+import { ListItem } from '@delightui/components';
+
+function BasicListItemExample() {
+  return (
+    <div>
+      <ListItem>
+        Basic List Item
+      </ListItem>
+      <ListItem>
+        Another List Item
+      </ListItem>
+      <ListItem>
+        Third List Item
+      </ListItem>
+    </div>
+  );
+}
+```
+
+### Clickable List Items
+
+```tsx
+import { ListItem } from '@delightui/components';
+
+function ClickableListItemExample() {
+  const handleItemClick = (item: string) => {
+    console.log(`Clicked: ${item}`);
+  };
+
+  return (
+    <div>
+      <ListItem onClick={() => handleItemClick('Home')}>
+        Home
+      </ListItem>
+      <ListItem onClick={() => handleItemClick('About')}>
+        About
+      </ListItem>
+      <ListItem onClick={() => handleItemClick('Services')}>
+        Services
+      </ListItem>
+      <ListItem onClick={() => handleItemClick('Contact')}>
+        Contact
+      </ListItem>
+    </div>
+  );
+}
+```
+
+### List Items with Icons
+
+```tsx
+import { ListItem, Icon } from '@delightui/components';
+
+function IconListItemExample() {
+  return (
+    <div>
+      <ListItem
+        leadingIcon={<Icon name="AddFilled" />}
+        onClick={() => console.log('Add clicked')}
+      >
+        Add New Item
+      </ListItem>
+      
+      <ListItem
+        leadingIcon={<Icon name="SearchFilled" />}
+        onClick={() => console.log('Search clicked')}
+      >
+        Search
+      </ListItem>
+      
+      <ListItem
+        leadingIcon={<Icon name="InfoFilled" />}
+        trailingIcon={<Icon name="ChevronRightOutlined" />}
+        onClick={() => console.log('Info clicked')}
+      >
+        Information
+      </ListItem>
+    </div>
+  );
+}
+```
+
+### Navigation Menu Example
+
+```tsx
+import { ListItem, Icon } from '@delightui/components';
+
+function NavigationMenuExample() {
+  const [activeItem, setActiveItem] = useState('dashboard');
+
+  const menuItems = [
+    { id: 'dashboard', label: 'Dashboard', icon: 'AddFilled' },
+    { id: 'users', label: 'Users', icon: 'SearchFilled' },
+    { id: 'settings', label: 'Settings', icon: 'InfoFilled' },
+    { id: 'help', label: 'Help', icon: 'ErrorOutlined' }
+  ];
+
+  return (
+    <nav style={{ width: '250px', border: '1px solid #ccc', borderRadius: '8px' }}>
+      {menuItems.map((item) => (
+        <ListItem
+          key={item.id}
+          leadingIcon={<Icon name={item.icon} />}
+          trailingIcon={activeItem === item.id ? <Icon name="CheckFilled" /> : undefined}
+          onClick={() => setActiveItem(item.id)}
+          className={activeItem === item.id ? 'active' : ''}
+        >
+          {item.label}
+        </ListItem>
+      ))}
+    </nav>
+  );
+}
+```
+
+### Settings List Example
+
+```tsx
+import { ListItem, Icon, Toggle } from '@delightui/components';
+
+function SettingsListExample() {
+  const [settings, setSettings] = useState({
+    notifications: true,
+    darkMode: false,
+    autoSync: true
+  });
+
+  const toggleSetting = (key: keyof typeof settings) => {
+    setSettings(prev => ({ ...prev, [key]: !prev[key] }));
+  };
+
+  return (
+    <div style={{ width: '300px' }}>
+      <ListItem
+        leadingIcon={<Icon name="InfoFilled" />}
+        trailingIcon={
+          <Toggle
+            value={settings.notifications}
+            onValueChange={() => toggleSetting('notifications')}
+          />
+        }
+      >
+        Notifications
+      </ListItem>
+      
+      <ListItem
+        leadingIcon={<Icon name="InfoFilled" />}
+        trailingIcon={
+          <Toggle
+            value={settings.darkMode}
+            onValueChange={() => toggleSetting('darkMode')}
+          />
+        }
+      >
+        Dark Mode
+      </ListItem>
+      
+      <ListItem
+        leadingIcon={<Icon name="InfoFilled" />}
+        trailingIcon={
+          <Toggle
+            value={settings.autoSync}
+            onValueChange={() => toggleSetting('autoSync')}
+          />
+        }
+      >
+        Auto Sync
+      </ListItem>
+    </div>
+  );
+}
+```
+
+### Disabled List Items
+
+```tsx
+import { ListItem, Icon } from '@delightui/components';
+
+function DisabledListItemExample() {
+  return (
+    <div>
+      <ListItem
+        leadingIcon={<Icon name="AddFilled" />}
+        onClick={() => console.log('Available action')}
+      >
+        Available Action
+      </ListItem>
+      
+      <ListItem
+        leadingIcon={<Icon name="SearchFilled" />}
+        disabled
+        onClick={() => console.log('This will not be called')}
+      >
+        Disabled Action
+      </ListItem>
+      
+      <ListItem
+        leadingIcon={<Icon name="InfoFilled" />}
+        onClick={() => console.log('Another available action')}
+      >
+        Another Available Action
+      </ListItem>
+    </div>
+  );
+}
+```
+
+### List with Different Content Types
+
+```tsx
+import { ListItem, Icon, Text, Button } from '@delightui/components';
+
+function ContentTypesListExample() {
+  return (
+    <div>
+      <ListItem leadingIcon={<Icon name="AddFilled" />}>
+        <div>
+          <Text weight="bold">John Doe</Text>
+          <Text size="small" color="secondary">
+            john.doe@example.com
+          </Text>
+        </div>
+      </ListItem>
+      
+      <ListItem leadingIcon={<Icon name="SearchFilled" />}>
+        <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', width: '100%' }}>
+          <div>
+            <Text weight="bold">Project Alpha</Text>
+            <Text size="small" color="secondary">
+              Due: Tomorrow
+            </Text>
+          </div>
+          <Button size="Small" type="Outlined">
+            View
+          </Button>
+        </div>
+      </ListItem>
+      
+      <ListItem>
+        <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
+          <div style={{ 
+            width: '40px', 
+            height: '40px', 
+            borderRadius: '50%', 
+            backgroundColor: '#007bff',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            color: 'white',
+            fontSize: '14px',
+            fontWeight: 'bold'
+          }}>
+            AB
+          </div>
+          <div>
+            <Text weight="bold">Alice Brown</Text>
+            <Text size="small" color="secondary">
+              Online
+            </Text>
+          </div>
+        </div>
+      </ListItem>
+    </div>
+  );
+}
+```
+
+### Grouped List Items
+
+```tsx
+import { ListItem, Icon, Text } from '@delightui/components';
+
+function GroupedListItemExample() {
+  const groups = [
+    {
+      title: 'Recent',
+      items: [
+        { id: 1, name: 'Document 1', icon: 'AddFilled' },
+        { id: 2, name: 'Document 2', icon: 'SearchFilled' }
+      ]
+    },
+    {
+      title: 'Favorites',
+      items: [
+        { id: 3, name: 'Important File', icon: 'InfoFilled' },
+        { id: 4, name: 'Starred Item', icon: 'CheckFilled' }
+      ]
+    }
+  ];
+
+  return (
+    <div>
+      {groups.map((group) => (
+        <div key={group.title}>
+          <Text 
+            weight="bold" 
+            size="small" 
+            color="secondary"
+            style={{ padding: '8px 16px', textTransform: 'uppercase' }}
+          >
+            {group.title}
+          </Text>
+          
+          {group.items.map((item) => (
+            <ListItem
+              key={item.id}
+              leadingIcon={<Icon name={item.icon} />}
+              trailingIcon={<Icon name="ChevronRightOutlined" />}
+              onClick={() => console.log(`Clicked ${item.name}`)}
+            >
+              {item.name}
+            </ListItem>
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Interactive List with Selection
+
+```tsx
+import { ListItem, Icon, Checkbox } from '@delightui/components';
+
+function SelectableListExample() {
+  const [selectedItems, setSelectedItems] = useState<number[]>([]);
+  
+  const items = [
+    { id: 1, name: 'Item 1' },
+    { id: 2, name: 'Item 2' },
+    { id: 3, name: 'Item 3' },
+    { id: 4, name: 'Item 4' }
+  ];
+
+  const toggleSelection = (itemId: number) => {
+    setSelectedItems(prev => 
+      prev.includes(itemId)
+        ? prev.filter(id => id !== itemId)
+        : [...prev, itemId]
+    );
+  };
+
+  const isSelected = (itemId: number) => selectedItems.includes(itemId);
+
+  return (
+    <div>
+      <Text weight="bold" style={{ marginBottom: '8px' }}>
+        Selected: {selectedItems.length} items
+      </Text>
+      
+      {items.map((item) => (
+        <ListItem
+          key={item.id}
+          leadingIcon={
+            <Checkbox
+              value={isSelected(item.id)}
+              onValueChange={() => toggleSelection(item.id)}
+            />
+          }
+          onClick={() => toggleSelection(item.id)}
+          className={isSelected(item.id) ? 'selected' : ''}
+        >
+          {item.name}
+        </ListItem>
+      ))}
+    </div>
+  );
+}
+```
+
+### Action List with Confirmation
+
+```tsx
+import { ListItem, Icon, Button } from '@delightui/components';
+
+function ActionListExample() {
+  const [showConfirm, setShowConfirm] = useState<number | null>(null);
+
+  const handleDelete = (id: number) => {
+    setShowConfirm(id);
+  };
+
+  const confirmDelete = (id: number) => {
+    console.log(`Deleting item ${id}`);
+    setShowConfirm(null);
+  };
+
+  const items = [
+    { id: 1, name: 'Item to Delete 1' },
+    { id: 2, name: 'Item to Delete 2' },
+    { id: 3, name: 'Item to Delete 3' }
+  ];
+
+  return (
+    <div>
+      {items.map((item) => (
+        <ListItem
+          key={item.id}
+          leadingIcon={<Icon name="InfoFilled" />}
+          trailingIcon={
+            showConfirm === item.id ? (
+              <div style={{ display: 'flex', gap: '8px' }}>
+                <Button
+                  size="Small"
+                  type="Outlined"
+                  onClick={() => setShowConfirm(null)}
+                >
+                  Cancel
+                </Button>
+                <Button
+                  size="Small"
+                  style="Destructive"
+                  onClick={() => confirmDelete(item.id)}
+                >
+                  Delete
+                </Button>
+              </div>
+            ) : (
+              <Button
+                size="Small"
+                type="Ghost"
+                onClick={() => handleDelete(item.id)}
+              >
+                <Icon name="CloseDeleteOutlined" />
+              </Button>
+            )
+          }
+        >
+          {item.name}
+        </ListItem>
+      ))}
+    </div>
+  );
+}
+```
+
+### Custom Styled List Items
+
+```tsx
+import { ListItem, Icon } from '@delightui/components';
+
+function CustomStyledListExample() {
+  return (
+    <div>
+      <ListItem
+        leadingIcon={<Icon name="CheckFilled" />}
+        className="success-item"
+        style={{ backgroundColor: '#d4edda', borderLeft: '4px solid #28a745' }}
+      >
+        Success Item
+      </ListItem>
+      
+      <ListItem
+        leadingIcon={<Icon name="ErrorOutlined" />}
+        className="warning-item"
+        style={{ backgroundColor: '#fff3cd', borderLeft: '4px solid #ffc107' }}
+      >
+        Warning Item
+      </ListItem>
+      
+      <ListItem
+        leadingIcon={<Icon name="InfoFilled" />}
+        className="info-item"
+        style={{ backgroundColor: '#d1ecf1', borderLeft: '4px solid #17a2b8' }}
+      >
+        Info Item
+      </ListItem>
+    </div>
+  );
+}
+```