@delightui/components 0.1.105 → 0.1.107

package/docs/components/molecules/Option.md

@@ -0,0 +1,521 @@
+# Option
+
+## Description
+
+A select dropdown option component that represents individual choices within Select components. Supports icons, disabled states, custom styling, and accessibility features for creating rich selection interfaces with proper keyboard navigation and screen reader support.
+
+## Aliases
+
+- Option
+- SelectOption
+- DropdownOption
+- Choice
+- ListOption
+
+## Props Breakdown
+
+**Extends:** `LiHTMLAttributes<HTMLLIElement>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `value` | `string \| number` | - | Yes | Value associated with the option |
+| `disabled` | `boolean` | `false` | No | Whether the option is disabled |
+| `leadingIcon` | `ReactNode` | - | No | Icon displayed before the option content |
+| `trailingIcon` | `ReactNode` | - | No | Icon displayed after the option content |
+| `className` | `string` | - | No | Additional CSS class names for custom styling |
+| `children` | `ReactNode` | - | Yes | Content of the option (text, elements, etc.) |
+| `closeSelectOptions` | `() => void` | - | No | Internal function to close select dropdown |
+
+Plus all standard HTML list item attributes (`id`, `style`, `onClick`, etc.).
+
+## Examples
+
+### Basic Usage
+```tsx
+import { Select, Option } from '@delightui/components';
+
+function BasicExample() {
+  return (
+    <Select placeholder="Choose an option">
+      <Option value="option1">Option 1</Option>
+      <Option value="option2">Option 2</Option>
+      <Option value="option3">Option 3</Option>
+      <Option value="option4">Option 4</Option>
+    </Select>
+  );
+}
+```
+
+### Options with Icons
+```tsx
+function IconOptionsExample() {
+  return (
+    <Select placeholder="Select a service">
+      <Option 
+        value="web" 
+        leadingIcon={<Icon icon="Web" />}
+      >
+        Web Development
+      </Option>
+      
+      <Option 
+        value="mobile" 
+        leadingIcon={<Icon icon="PhoneAndroid" />}
+      >
+        Mobile Development
+      </Option>
+      
+      <Option 
+        value="design" 
+        leadingIcon={<Icon icon="Palette" />}
+      >
+        UI/UX Design
+      </Option>
+      
+      <Option 
+        value="consulting" 
+        leadingIcon={<Icon icon="Business" />}
+        trailingIcon={<Icon icon="Star" />}
+      >
+        Business Consulting
+      </Option>
+    </Select>
+  );
+}
+```
+
+### Disabled Options
+```tsx
+function DisabledOptionsExample() {
+  return (
+    <Select placeholder="Select a plan">
+      <Option value="free" leadingIcon={<Icon icon="Free" />}>
+        Free Plan
+      </Option>
+      
+      <Option value="basic" leadingIcon={<Icon icon="Basic" />}>
+        Basic Plan - $9/month
+      </Option>
+      
+      <Option 
+        value="premium" 
+        leadingIcon={<Icon icon="Premium" />}
+        disabled
+      >
+        Premium Plan - Coming Soon
+      </Option>
+      
+      <Option 
+        value="enterprise" 
+        leadingIcon={<Icon icon="Enterprise" />}
+        disabled
+      >
+        Enterprise Plan - Contact Sales
+      </Option>
+    </Select>
+  );
+}
+```
+
+### Country/Region Selection
+```tsx
+function CountrySelectExample() {
+  const countries = [
+    { code: 'us', name: 'United States', flag: 'πΊπΈ' },
+    { code: 'uk', name: 'United Kingdom', flag: 'π¬π§' },
+    { code: 'ca', name: 'Canada', flag: 'π¨π¦' },
+    { code: 'au', name: 'Australia', flag: 'π¦πΊ' },
+    { code: 'de', name: 'Germany', flag: 'π©πͺ' },
+    { code: 'fr', name: 'France', flag: 'π«π·' },
+    { code: 'jp', name: 'Japan', flag: 'π―π΅' }
+  ];
+
+  return (
+    <Select placeholder="Select your country">
+      {countries.map(country => (
+        <Option 
+          key={country.code}
+          value={country.code}
+          leadingIcon={<Text>{country.flag}</Text>}
+        >
+          {country.name}
+        </Option>
+      ))}
+    </Select>
+  );
+}
+```
+
+### Options with Descriptions
+```tsx
+function DescriptiveOptionsExample() {
+  return (
+    <Select placeholder="Choose your subscription">
+      <Option value="starter" className="descriptive-option">
+        <div className="option-content">
+          <div className="option-header">
+            <Icon icon="Rocket" />
+            <Text type="BodyMedium">Starter Plan</Text>
+            <Chip size="Small" style="Success">Popular</Chip>
+          </div>
+          <Text type="BodySmall" className="option-description">
+            Perfect for individuals and small teams
+          </Text>
+          <Text type="BodySmall" className="option-price">
+            $9/month
+          </Text>
+        </div>
+      </Option>
+      
+      <Option value="professional" className="descriptive-option">
+        <div className="option-content">
+          <div className="option-header">
+            <Icon icon="Business" />
+            <Text type="BodyMedium">Professional Plan</Text>
+          </div>
+          <Text type="BodySmall" className="option-description">
+            Advanced features for growing businesses
+          </Text>
+          <Text type="BodySmall" className="option-price">
+            $29/month
+          </Text>
+        </div>
+      </Option>
+      
+      <Option value="enterprise" className="descriptive-option">
+        <div className="option-content">
+          <div className="option-header">
+            <Icon icon="Enterprise" />
+            <Text type="BodyMedium">Enterprise Plan</Text>
+          </div>
+          <Text type="BodySmall" className="option-description">
+            Full-scale solution for large organizations
+          </Text>
+          <Text type="BodySmall" className="option-price">
+            Custom pricing
+          </Text>
+        </div>
+      </Option>
+    </Select>
+  );
+}
+```
+
+### Status/Priority Options
+```tsx
+function StatusOptionsExample() {
+  return (
+    <Select placeholder="Set priority level">
+      <Option 
+        value="critical" 
+        leadingIcon={<Icon icon="PriorityHigh" style={{ color: '#d32f2f' }} />}
+      >
+        <Text style={{ color: '#d32f2f' }}>Critical</Text>
+      </Option>
+      
+      <Option 
+        value="high" 
+        leadingIcon={<Icon icon="ArrowUpward" style={{ color: '#f57c00' }} />}
+      >
+        <Text style={{ color: '#f57c00' }}>High Priority</Text>
+      </Option>
+      
+      <Option 
+        value="medium" 
+        leadingIcon={<Icon icon="Remove" style={{ color: '#1976d2' }} />}
+      >
+        <Text style={{ color: '#1976d2' }}>Medium Priority</Text>
+      </Option>
+      
+      <Option 
+        value="low" 
+        leadingIcon={<Icon icon="ArrowDownward" style={{ color: '#388e3c' }} />}
+      >
+        <Text style={{ color: '#388e3c' }}>Low Priority</Text>
+      </Option>
+    </Select>
+  );
+}
+```
+
+### Team Member Selection
+```tsx
+function TeamMemberOptionsExample() {
+  const teamMembers = [
+    { 
+      id: 'john', 
+      name: 'John Doe', 
+      role: 'Developer', 
+      avatar: '/avatars/john.jpg',
+      status: 'online'
+    },
+    { 
+      id: 'jane', 
+      name: 'Jane Smith', 
+      role: 'Designer', 
+      avatar: '/avatars/jane.jpg',
+      status: 'busy'
+    },
+    { 
+      id: 'mike', 
+      name: 'Mike Johnson', 
+      role: 'Project Manager', 
+      avatar: '/avatars/mike.jpg',
+      status: 'offline'
+    }
+  ];
+
+  return (
+    <Select placeholder="Assign to team member">
+      {teamMembers.map(member => (
+        <Option 
+          key={member.id}
+          value={member.id}
+          className="team-member-option"
+          disabled={member.status === 'offline'}
+        >
+          <div className="member-info">
+            <div className="member-avatar">
+              <Image 
+                src={member.avatar} 
+                alt={member.name}
+                size="Small"
+              />
+              <div className={`status-indicator ${member.status}`} />
+            </div>
+            
+            <div className="member-details">
+              <Text type="BodyMedium">{member.name}</Text>
+              <Text type="BodySmall" className="member-role">
+                {member.role}
+              </Text>
+            </div>
+            
+            <div className="member-status">
+              <Chip 
+                size="Small" 
+                style={
+                  member.status === 'online' ? 'Success' : 
+                  member.status === 'busy' ? 'Warning' : 'Default'
+                }
+              >
+                {member.status}
+              </Chip>
+            </div>
+          </div>
+        </Option>
+      ))}
+    </Select>
+  );
+}
+```
+
+### Grouped Options
+```tsx
+function GroupedOptionsExample() {
+  return (
+    <Select placeholder="Select a technology">
+      <optgroup label="Frontend">
+        <Option value="react" leadingIcon={<Icon icon="React" />}>
+          React
+        </Option>
+        <Option value="vue" leadingIcon={<Icon icon="Vue" />}>
+          Vue.js
+        </Option>
+        <Option value="angular" leadingIcon={<Icon icon="Angular" />}>
+          Angular
+        </Option>
+      </optgroup>
+      
+      <optgroup label="Backend">
+        <Option value="node" leadingIcon={<Icon icon="NodeJS" />}>
+          Node.js
+        </Option>
+        <Option value="python" leadingIcon={<Icon icon="Python" />}>
+          Python
+        </Option>
+        <Option value="java" leadingIcon={<Icon icon="Java" />}>
+          Java
+        </Option>
+      </optgroup>
+      
+      <optgroup label="Database">
+        <Option value="mongodb" leadingIcon={<Icon icon="Database" />}>
+          MongoDB
+        </Option>
+        <Option value="postgresql" leadingIcon={<Icon icon="Database" />}>
+          PostgreSQL
+        </Option>
+        <Option value="mysql" leadingIcon={<Icon icon="Database" />}>
+          MySQL
+        </Option>
+      </optgroup>
+    </Select>
+  );
+}
+```
+
+### Multi-select Options
+```tsx
+function MultiSelectOptionsExample() {
+  const [selectedTags, setSelectedTags] = useState([]);
+
+  const tags = [
+    { id: 'urgent', label: 'Urgent', color: '#d32f2f' },
+    { id: 'important', label: 'Important', color: '#f57c00' },
+    { id: 'feature', label: 'Feature', color: '#1976d2' },
+    { id: 'bug', label: 'Bug Fix', color: '#d32f2f' },
+    { id: 'improvement', label: 'Improvement', color: '#388e3c' },
+    { id: 'documentation', label: 'Documentation', color: '#7b1fa2' }
+  ];
+
+  return (
+    <Select 
+      multiple
+      value={selectedTags}
+      onValueChange={setSelectedTags}
+      placeholder="Select tags"
+    >
+      {tags.map(tag => (
+        <Option 
+          key={tag.id}
+          value={tag.id}
+          leadingIcon={
+            <div 
+              className="tag-color-indicator"
+              style={{ backgroundColor: tag.color }}
+            />
+          }
+          trailingIcon={
+            selectedTags.includes(tag.id) ? (
+              <Icon icon="Check" />
+            ) : null
+          }
+        >
+          {tag.label}
+        </Option>
+      ))}
+    </Select>
+  );
+}
+```
+
+### Search Results Options
+```tsx
+function SearchResultsOptionsExample() {
+  const [searchTerm, setSearchTerm] = useState('');
+  
+  const searchResults = [
+    { 
+      id: 1, 
+      title: 'React Best Practices', 
+      category: 'Development',
+      description: 'Learn the latest React patterns and techniques'
+    },
+    { 
+      id: 2, 
+      title: 'Design System Guidelines', 
+      category: 'Design',
+      description: 'Comprehensive guide to building design systems'
+    },
+    { 
+      id: 3, 
+      title: 'API Documentation', 
+      category: 'Documentation',
+      description: 'Complete API reference and examples'
+    }
+  ];
+
+  const filteredResults = searchResults.filter(result =>
+    result.title.toLowerCase().includes(searchTerm.toLowerCase()) ||
+    result.description.toLowerCase().includes(searchTerm.toLowerCase())
+  );
+
+  return (
+    <div className="search-select">
+      <Input 
+        placeholder="Search..."
+        value={searchTerm}
+        onValueChange={setSearchTerm}
+        leadingIcon={<Icon icon="Search" />}
+      />
+      
+      <Select placeholder="Select from results">
+        {filteredResults.map(result => (
+          <Option 
+            key={result.id}
+            value={result.id}
+            className="search-result-option"
+          >
+            <div className="result-content">
+              <div className="result-header">
+                <Text type="BodyMedium">{result.title}</Text>
+                <Chip size="Small">{result.category}</Chip>
+              </div>
+              <Text type="BodySmall" className="result-description">
+                {result.description}
+              </Text>
+            </div>
+          </Option>
+        ))}
+        
+        {filteredResults.length === 0 && (
+          <Option value="" disabled>
+            <Text type="BodySmall">No results found</Text>
+          </Option>
+        )}
+      </Select>
+    </div>
+  );
+}
+```
+
+### Custom Styled Options
+```tsx
+function CustomStyledOptionsExample() {
+  return (
+    <Select placeholder="Choose your theme">
+      <Option 
+        value="light"
+        className="theme-option light-theme"
+        leadingIcon={<Icon icon="LightMode" />}
+      >
+        <div className="theme-content">
+          <Text type="BodyMedium">Light Theme</Text>
+          <div className="theme-preview">
+            <div className="color-swatch" style={{ backgroundColor: '#ffffff' }} />
+            <div className="color-swatch" style={{ backgroundColor: '#f5f5f5' }} />
+            <div className="color-swatch" style={{ backgroundColor: '#e0e0e0' }} />
+          </div>
+        </div>
+      </Option>
+      
+      <Option 
+        value="dark"
+        className="theme-option dark-theme"
+        leadingIcon={<Icon icon="DarkMode" />}
+      >
+        <div className="theme-content">
+          <Text type="BodyMedium">Dark Theme</Text>
+          <div className="theme-preview">
+            <div className="color-swatch" style={{ backgroundColor: '#121212' }} />
+            <div className="color-swatch" style={{ backgroundColor: '#1e1e1e' }} />
+            <div className="color-swatch" style={{ backgroundColor: '#333333' }} />
+          </div>
+        </div>
+      </Option>
+      
+      <Option 
+        value="auto"
+        className="theme-option auto-theme"
+        leadingIcon={<Icon icon="AutoMode" />}
+      >
+        <div className="theme-content">
+          <Text type="BodyMedium">Auto Theme</Text>
+          <Text type="BodySmall">Follows system preference</Text>
+        </div>
+      </Option>
+    </Select>
+  );
+}
+```