@delightui/components 0.1.104 → 0.1.106

package/docs/components/atoms/SelectListItem.md

@@ -0,0 +1,609 @@
+# SelectListItem
+
+A specialized list item component designed specifically for use within select dropdowns and option lists. It provides a consistent interface for selectable options with support for icons, disabled states, and click interactions. This component is optimized for use within select components and dropdown menus.
+
+## Aliases
+
+- SelectListItem
+- SelectOption
+- DropdownItem
+
+## 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 |
+
+Plus all standard HTML div attributes (id, title, aria-*, data-*, etc.).
+
+## Examples
+
+### Basic Select List Items
+
+```tsx
+import { SelectListItem } from '@delightui/components';
+
+function BasicSelectListExample() {
+  const [selectedOption, setSelectedOption] = useState('');
+
+  const options = ['Option 1', 'Option 2', 'Option 3'];
+
+  return (
+    <div style={{ 
+      border: '1px solid #ccc', 
+      borderRadius: '4px', 
+      maxWidth: '200px' 
+    }}>
+      {options.map((option, index) => (
+        <SelectListItem
+          key={index}
+          onClick={() => setSelectedOption(option)}
+          className={selectedOption === option ? 'selected' : ''}
+        >
+          {option}
+        </SelectListItem>
+      ))}
+    </div>
+  );
+}
+```
+
+### Select List with Icons
+
+```tsx
+import { SelectListItem, Icon } from '@delightui/components';
+
+function IconSelectListExample() {
+  const [selectedOption, setSelectedOption] = useState('');
+
+  const options = [
+    { value: 'home', label: 'Home', icon: 'AddFilled' },
+    { value: 'profile', label: 'Profile', icon: 'SearchFilled' },
+    { value: 'settings', label: 'Settings', icon: 'InfoFilled' },
+    { value: 'help', label: 'Help', icon: 'ErrorOutlined' }
+  ];
+
+  return (
+    <div style={{ 
+      border: '1px solid #ccc', 
+      borderRadius: '4px', 
+      maxWidth: '250px' 
+    }}>
+      {options.map((option) => (
+        <SelectListItem
+          key={option.value}
+          leadingIcon={<Icon name={option.icon} />}
+          trailingIcon={selectedOption === option.value ? <Icon name="CheckFilled" /> : undefined}
+          onClick={() => setSelectedOption(option.value)}
+          className={selectedOption === option.value ? 'selected' : ''}
+        >
+          {option.label}
+        </SelectListItem>
+      ))}
+    </div>
+  );
+}
+```
+
+### Country Selector
+
+```tsx
+import { SelectListItem, Text } from '@delightui/components';
+
+function CountrySelectorExample() {
+  const [selectedCountry, setSelectedCountry] = useState('');
+
+  const countries = [
+    { code: 'US', name: 'United States', flag: '🇺🇸' },
+    { code: 'CA', name: 'Canada', flag: '🇨🇦' },
+    { code: 'UK', name: 'United Kingdom', flag: '🇬🇧' },
+    { code: 'DE', name: 'Germany', flag: '🇩🇪' },
+    { code: 'FR', name: 'France', flag: '🇫🇷' },
+    { code: 'JP', name: 'Japan', flag: '🇯🇵' }
+  ];
+
+  return (
+    <div style={{ 
+      border: '1px solid #ccc', 
+      borderRadius: '4px', 
+      maxWidth: '300px',
+      maxHeight: '200px',
+      overflowY: 'auto'
+    }}>
+      {countries.map((country) => (
+        <SelectListItem
+          key={country.code}
+          leadingIcon={<span style={{ fontSize: '18px' }}>{country.flag}</span>}
+          onClick={() => setSelectedCountry(country.code)}
+          className={selectedCountry === country.code ? 'selected' : ''}
+        >
+          <div>
+            <Text weight="medium">{country.name}</Text>
+            <Text size="small" color="secondary" style={{ display: 'block' }}>
+              {country.code}
+            </Text>
+          </div>
+        </SelectListItem>
+      ))}
+    </div>
+  );
+}
+```
+
+### User Selection List
+
+```tsx
+import { SelectListItem, Text } from '@delightui/components';
+
+function UserSelectionExample() {
+  const [selectedUser, setSelectedUser] = useState('');
+
+  const users = [
+    { id: '1', name: 'John Doe', email: 'john@example.com', role: 'Admin' },
+    { id: '2', name: 'Jane Smith', email: 'jane@example.com', role: 'Editor' },
+    { id: '3', name: 'Bob Johnson', email: 'bob@example.com', role: 'Viewer' },
+    { id: '4', name: 'Alice Brown', email: 'alice@example.com', role: 'Editor' }
+  ];
+
+  return (
+    <div style={{ 
+      border: '1px solid #ccc', 
+      borderRadius: '4px', 
+      maxWidth: '350px' 
+    }}>
+      {users.map((user) => (
+        <SelectListItem
+          key={user.id}
+          leadingIcon={
+            <div style={{
+              width: '32px',
+              height: '32px',
+              borderRadius: '50%',
+              backgroundColor: '#007bff',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              color: 'white',
+              fontSize: '12px',
+              fontWeight: 'bold'
+            }}>
+              {user.name.split(' ').map(n => n[0]).join('')}
+            </div>
+          }
+          onClick={() => setSelectedUser(user.id)}
+          className={selectedUser === user.id ? 'selected' : ''}
+        >
+          <div>
+            <Text weight="medium">{user.name}</Text>
+            <Text size="small" color="secondary" style={{ display: 'block' }}>
+              {user.email}
+            </Text>
+            <Text size="small" color="primary" style={{ display: 'block' }}>
+              {user.role}
+            </Text>
+          </div>
+        </SelectListItem>
+      ))}
+    </div>
+  );
+}
+```
+
+### Priority Selection
+
+```tsx
+import { SelectListItem, Icon, Text } from '@delightui/components';
+
+function PrioritySelectionExample() {
+  const [selectedPriority, setSelectedPriority] = useState('');
+
+  const priorities = [
+    { 
+      value: 'low', 
+      label: 'Low Priority', 
+      color: '#28a745',
+      icon: 'InfoFilled',
+      description: 'Not urgent, can be done later'
+    },
+    { 
+      value: 'medium', 
+      label: 'Medium Priority', 
+      color: '#ffc107',
+      icon: 'InfoFilled',
+      description: 'Should be completed soon'
+    },
+    { 
+      value: 'high', 
+      label: 'High Priority', 
+      color: '#fd7e14',
+      icon: 'ErrorOutlined',
+      description: 'Important, needs attention'
+    },
+    { 
+      value: 'urgent', 
+      label: 'Urgent', 
+      color: '#dc3545',
+      icon: 'ErrorOutlined',
+      description: 'Critical, immediate action required'
+    }
+  ];
+
+  return (
+    <div style={{ 
+      border: '1px solid #ccc', 
+      borderRadius: '4px', 
+      maxWidth: '300px' 
+    }}>
+      {priorities.map((priority) => (
+        <SelectListItem
+          key={priority.value}
+          leadingIcon={
+            <Icon 
+              name={priority.icon} 
+              style={{ color: priority.color }}
+            />
+          }
+          trailingIcon={
+            selectedPriority === priority.value ? 
+            <Icon name="CheckFilled" style={{ color: '#28a745' }} /> : 
+            undefined
+          }
+          onClick={() => setSelectedPriority(priority.value)}
+          className={selectedPriority === priority.value ? 'selected' : ''}
+        >
+          <div>
+            <Text weight="medium" style={{ color: priority.color }}>
+              {priority.label}
+            </Text>
+            <Text size="small" color="secondary" style={{ display: 'block' }}>
+              {priority.description}
+            </Text>
+          </div>
+        </SelectListItem>
+      ))}
+    </div>
+  );
+}
+```
+
+### File Type Selection
+
+```tsx
+import { SelectListItem, Icon, Text } from '@delightui/components';
+
+function FileTypeSelectionExample() {
+  const [selectedFileType, setSelectedFileType] = useState('');
+
+  const fileTypes = [
+    { 
+      type: 'pdf', 
+      label: 'PDF Document', 
+      extension: '.pdf',
+      icon: 'AddFilled',
+      description: 'Portable Document Format'
+    },
+    { 
+      type: 'doc', 
+      label: 'Word Document', 
+      extension: '.docx',
+      icon: 'AddFilled',
+      description: 'Microsoft Word Document'
+    },
+    { 
+      type: 'excel', 
+      label: 'Excel Spreadsheet', 
+      extension: '.xlsx',
+      icon: 'AddFilled',
+      description: 'Microsoft Excel Spreadsheet'
+    },
+    { 
+      type: 'image', 
+      label: 'Image File', 
+      extension: '.jpg, .png',
+      icon: 'SearchFilled',
+      description: 'JPEG or PNG Image'
+    }
+  ];
+
+  return (
+    <div style={{ 
+      border: '1px solid #ccc', 
+      borderRadius: '4px', 
+      maxWidth: '350px' 
+    }}>
+      {fileTypes.map((fileType) => (
+        <SelectListItem
+          key={fileType.type}
+          leadingIcon={<Icon name={fileType.icon} />}
+          onClick={() => setSelectedFileType(fileType.type)}
+          className={selectedFileType === fileType.type ? 'selected' : ''}
+        >
+          <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', width: '100%' }}>
+            <div>
+              <Text weight="medium">{fileType.label}</Text>
+              <Text size="small" color="secondary" style={{ display: 'block' }}>
+                {fileType.description}
+              </Text>
+            </div>
+            <Text size="small" color="primary" weight="medium">
+              {fileType.extension}
+            </Text>
+          </div>
+        </SelectListItem>
+      ))}
+    </div>
+  );
+}
+```
+
+### Disabled Options
+
+```tsx
+import { SelectListItem, Icon, Text } from '@delightui/components';
+
+function DisabledOptionsExample() {
+  const [selectedOption, setSelectedOption] = useState('');
+
+  const options = [
+    { value: 'option1', label: 'Available Option 1', disabled: false },
+    { value: 'option2', label: 'Available Option 2', disabled: false },
+    { value: 'option3', label: 'Disabled Option 3', disabled: true },
+    { value: 'option4', label: 'Available Option 4', disabled: false },
+    { value: 'option5', label: 'Disabled Option 5', disabled: true }
+  ];
+
+  return (
+    <div style={{ 
+      border: '1px solid #ccc', 
+      borderRadius: '4px', 
+      maxWidth: '250px' 
+    }}>
+      {options.map((option) => (
+        <SelectListItem
+          key={option.value}
+          disabled={option.disabled}
+          onClick={option.disabled ? undefined : () => setSelectedOption(option.value)}
+          className={selectedOption === option.value ? 'selected' : ''}
+          trailingIcon={
+            option.disabled ? 
+            <Icon name="ErrorOutlined" style={{ color: '#6c757d' }} /> : 
+            (selectedOption === option.value ? <Icon name="CheckFilled" /> : undefined)
+          }
+        >
+          <Text color={option.disabled ? 'secondary' : 'default'}>
+            {option.label}
+          </Text>
+        </SelectListItem>
+      ))}
+    </div>
+  );
+}
+```
+
+### Theme Selection
+
+```tsx
+import { SelectListItem, Text } from '@delightui/components';
+
+function ThemeSelectionExample() {
+  const [selectedTheme, setSelectedTheme] = useState('light');
+
+  const themes = [
+    {
+      value: 'light',
+      name: 'Light Theme',
+      description: 'Clean and bright interface',
+      preview: '#ffffff'
+    },
+    {
+      value: 'dark',
+      name: 'Dark Theme',
+      description: 'Easy on the eyes for low light',
+      preview: '#1a1a1a'
+    },
+    {
+      value: 'blue',
+      name: 'Blue Theme',
+      description: 'Professional blue color scheme',
+      preview: '#007bff'
+    },
+    {
+      value: 'green',
+      name: 'Green Theme',
+      description: 'Nature-inspired green palette',
+      preview: '#28a745'
+    }
+  ];
+
+  return (
+    <div style={{ 
+      border: '1px solid #ccc', 
+      borderRadius: '4px', 
+      maxWidth: '300px' 
+    }}>
+      {themes.map((theme) => (
+        <SelectListItem
+          key={theme.value}
+          leadingIcon={
+            <div style={{
+              width: '24px',
+              height: '24px',
+              borderRadius: '4px',
+              backgroundColor: theme.preview,
+              border: '1px solid #ddd'
+            }} />
+          }
+          trailingIcon={
+            selectedTheme === theme.value ? 
+            <Icon name="CheckFilled" style={{ color: '#28a745' }} /> : 
+            undefined
+          }
+          onClick={() => setSelectedTheme(theme.value)}
+          className={selectedTheme === theme.value ? 'selected' : ''}
+        >
+          <div>
+            <Text weight="medium">{theme.name}</Text>
+            <Text size="small" color="secondary" style={{ display: 'block' }}>
+              {theme.description}
+            </Text>
+          </div>
+        </SelectListItem>
+      ))}
+    </div>
+  );
+}
+```
+
+### Searchable Select List
+
+```tsx
+import { SelectListItem, Input, Text, Icon } from '@delightui/components';
+
+function SearchableSelectListExample() {
+  const [searchTerm, setSearchTerm] = useState('');
+  const [selectedItem, setSelectedItem] = useState('');
+
+  const allItems = [
+    'Apple', 'Banana', 'Cherry', 'Date', 'Elderberry',
+    'Fig', 'Grape', 'Honeydew', 'Kiwi', 'Lemon',
+    'Mango', 'Orange', 'Papaya', 'Quince', 'Raspberry'
+  ];
+
+  const filteredItems = allItems.filter(item =>
+    item.toLowerCase().includes(searchTerm.toLowerCase())
+  );
+
+  return (
+    <div style={{ 
+      border: '1px solid #ccc', 
+      borderRadius: '4px', 
+      maxWidth: '250px' 
+    }}>
+      <div style={{ padding: '8px', borderBottom: '1px solid #eee' }}>
+        <Input
+          value={searchTerm}
+          onValueChange={setSearchTerm}
+          placeholder="Search fruits..."
+          leadingIcon={<Icon name="SearchFilled" />}
+        />
+      </div>
+      
+      <div style={{ maxHeight: '200px', overflowY: 'auto' }}>
+        {filteredItems.length > 0 ? (
+          filteredItems.map((item) => (
+            <SelectListItem
+              key={item}
+              onClick={() => setSelectedItem(item)}
+              className={selectedItem === item ? 'selected' : ''}
+              trailingIcon={
+                selectedItem === item ? 
+                <Icon name="CheckFilled" style={{ color: '#28a745' }} /> : 
+                undefined
+              }
+            >
+              {item}
+            </SelectListItem>
+          ))
+        ) : (
+          <div style={{ padding: '16px', textAlign: 'center' }}>
+            <Text color="secondary" size="small">
+              No items found
+            </Text>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+### Multi-level Selection
+
+```tsx
+import { SelectListItem, Icon, Text } from '@delightui/components';
+
+function MultiLevelSelectionExample() {
+  const [selectedCategory, setSelectedCategory] = useState('');
+  const [selectedSubcategory, setSelectedSubcategory] = useState('');
+
+  const categories = [
+    {
+      id: 'electronics',
+      name: 'Electronics',
+      subcategories: ['Computers', 'Phones', 'Tablets']
+    },
+    {
+      id: 'clothing',
+      name: 'Clothing',
+      subcategories: ['Shirts', 'Pants', 'Shoes']
+    },
+    {
+      id: 'books',
+      name: 'Books',
+      subcategories: ['Fiction', 'Non-Fiction', 'Technical']
+    }
+  ];
+
+  const selectedCategoryData = categories.find(cat => cat.id === selectedCategory);
+
+  return (
+    <div style={{ display: 'flex', gap: '16px' }}>
+      <div style={{ 
+        border: '1px solid #ccc', 
+        borderRadius: '4px', 
+        minWidth: '200px' 
+      }}>
+        <div style={{ padding: '8px', borderBottom: '1px solid #eee', backgroundColor: '#f8f9fa' }}>
+          <Text weight="bold" size="small">Categories</Text>
+        </div>
+        {categories.map((category) => (
+          <SelectListItem
+            key={category.id}
+            onClick={() => {
+              setSelectedCategory(category.id);
+              setSelectedSubcategory('');
+            }}
+            className={selectedCategory === category.id ? 'selected' : ''}
+            trailingIcon={<Icon name="ChevronRightOutlined" />}
+          >
+            {category.name}
+          </SelectListItem>
+        ))}
+      </div>
+
+      {selectedCategoryData && (
+        <div style={{ 
+          border: '1px solid #ccc', 
+          borderRadius: '4px', 
+          minWidth: '200px' 
+        }}>
+          <div style={{ padding: '8px', borderBottom: '1px solid #eee', backgroundColor: '#f8f9fa' }}>
+            <Text weight="bold" size="small">Subcategories</Text>
+          </div>
+          {selectedCategoryData.subcategories.map((subcategory) => (
+            <SelectListItem
+              key={subcategory}
+              onClick={() => setSelectedSubcategory(subcategory)}
+              className={selectedSubcategory === subcategory ? 'selected' : ''}
+              trailingIcon={
+                selectedSubcategory === subcategory ? 
+                <Icon name="CheckFilled" style={{ color: '#28a745' }} /> : 
+                undefined
+              }
+            >
+              {subcategory}
+            </SelectListItem>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```