@ceed/ads 1.20.0 → 1.20.1

package/dist/components/inputs/Select.md

@@ -2,6 +2,8 @@
 
 ## Introduction
 
+The Select component is a form input that allows users to choose one or multiple options from a predefined list. Built on Joy UI's Select, it provides a dropdown interface for selecting values within forms. Select is designed for data input scenarios where users need to pick from a set of options, making it ideal for forms, filters, and configuration settings.
+
 ```tsx
 <Select options={options} />
 ```
@@ -22,8 +24,53 @@
 | onChange       | —           | —       |
 | options        | —           | options |
 
+> ⚠️ **Don't Confuse Select with Dropdown** ⚠️
+>
+> - **Select**: For form value selection - the selected value becomes form data
+> - **Dropdown**: For menus and action lists - triggers actions or navigation
+>
+> Choose the right component:
+>
+> - Less than 5 options → Consider RadioButton or RadioGroup
+> - More than 20 options → Consider Autocomplete with search
+> - Actions/navigation → Use Dropdown with Menu
+
+## Usage
+
+```tsx
+import { Select } from '@ceed/ads';
+
+const options = [
+  { value: 'dog', label: 'Dog' },
+  { value: 'cat', label: 'Cat' },
+  { value: 'fish', label: 'Fish' },
+];
+
+function MyComponent() {
+  return (
+    <Select
+      label="Choose a pet"
+      options={options}
+      defaultValue="dog"
+    />
+  );
+}
+```
+
+## Examples
+
+### Basic Select
+
+The default Select with a list of options.
+
+```tsx
+<Select options={options} />
+```
+
 ### Variants
 
+Select supports different visual styles.
+
 ```tsx
 <Stack spacing={4}>
   <Select defaultValue="dog" options={options} />
@@ -35,6 +82,8 @@
 
 ### Sizes
 
+Select comes in different sizes.
+
 ```tsx
 <Stack spacing={4}>
   <Select defaultValue="dog" size="sm" options={options} />
@@ -45,6 +94,8 @@
 
 ### Colors
 
+Apply semantic colors to Select.
+
 ```tsx
 <Stack spacing={4}>
   <Select defaultValue="dog" color="primary" options={options} />
@@ -54,3 +105,552 @@
   <Select defaultValue="dog" color="warning" options={options} />
 </Stack>
 ```
+
+### With Decorators
+
+Add icons or badges to the Select.
+
+```tsx
+<Select placeholder="Select a pet…" startDecorator={<FavoriteBorder />} endDecorator={<Chip size="sm" color="danger" variant="soft">
+  +5
+</Chip>} sx={{
+width: 240
+}} options={options} />
+```
+
+### With Label
+
+Select with an associated label.
+
+```tsx
+<>
+  <Select label="Label" defaultValue="dog" options={options} />
+</>
+```
+
+### With Helper Text
+
+Add helper text for additional context.
+
+```tsx
+<>
+  <Select label="Select" helperText="I'm helper text" defaultValue="dog" options={options} />
+</>
+```
+
+### Error State
+
+Show validation errors.
+
+```tsx
+<>
+  <Select label="label" error defaultValue="dog" options={options} />
+</>
+```
+
+### Form Control
+
+Complete form integration with label and helper text.
+
+```tsx
+<>
+  <Select label="Label" helperText="I'm helper text" defaultValue="dog" options={options} />
+  <Select label="Label" helperText="I'm helper text" defaultValue="dog" error options={options} />
+</>
+```
+
+### Required Field
+
+Mark the Select as required.
+
+```tsx
+<Select
+  options={options}
+  label="Label"
+  helperText="I'm helper text"
+  required
+/>
+```
+
+### Multiple Selection
+
+Allow selecting multiple options.
+
+```tsx
+<Select
+  options={options}
+  label="Label"
+  helperText="I'm helper text"
+  defaultValue={['dog']}
+  multiple
+/>
+```
+
+### Controlled Select
+
+Programmatically control the selected value.
+
+```tsx
+<div>
+  <Select {...args} options={options} value={value} onChange={(event, newValue) => {
+    setValue(newValue);
+    args.onChange?.(event, newValue);
+  }} />
+  <Select {...args} options={['dog', 'cat', 'fish', 'bird'] as string[]} value={value} onChange={(event, newValue) => {
+    setValue(newValue);
+    args.onChange?.(event, newValue);
+  }} />
+  <Select {...args} options={['dog', 'cat', 'fish', 'bird'] as string[]} value={[value]} onChange={(event, newValue) => {
+    setValue(newValue);
+    args.onChange?.(event, newValue);
+  }} multiple />
+</div>
+```
+
+### Disabled Options
+
+Individual options can be disabled.
+
+```tsx
+<Select
+  options={options.map((option, idx) => ({
+  ...option,
+  disabled: idx % 2 === 0
+}))}
+  label="Disabled Options"
+  defaultValue="dog"
+/>
+```
+
+### Options with Secondary Text
+
+Display additional information for each option.
+
+```tsx
+<Stack spacing={4} direction="row" alignItems="flex-start">
+  {sizes.map(size => <Stack key={size} spacing={1}>
+  <span style={{
+    color: '#6366f1',
+    fontSize: 12
+  }}>{size}</span>
+  <Select placeholder="Placeholder" options={optionsWithSecondaryText} sx={{
+    minWidth: 200
+  }} size={size} />
+</Stack>)}
+</Stack>
+```
+
+## When to Use
+
+### ✅ Good Use Cases
+
+- **Forms**: When users need to select a value that will be submitted as form data
+- **Filters**: Selecting filter criteria for lists or search results
+- **Settings**: Configuration options where user needs to pick one value
+- **Data entry**: Standardized input where free text isn't appropriate
+- **5-20 options**: Ideal number of choices for a Select
+- **Single source of truth**: When the selected value should be clearly visible
+
+### ❌ When Not to Use
+
+- **Actions/navigation**: Use Dropdown with Menu instead
+- **2-4 options visible at once**: Consider RadioGroup for better visibility
+- **20+ options**: Use Autocomplete with search functionality
+- **Complex selections**: Consider a different pattern if selections involve complex logic
+- **Toggle between states**: Use Switch or Checkbox instead
+
+## Common Use Cases
+
+### Form with Select
+
+```tsx
+function UserForm() {
+  const [country, setCountry] = useState('');
+  const [role, setRole] = useState('');
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <Stack spacing={2}>
+        <Select
+          label="Country"
+          required
+          value={country}
+          onChange={(e, val) => setCountry(val)}
+          options={countries}
+          placeholder="Select your country"
+        />
+
+        <Select
+          label="Role"
+          required
+          value={role}
+          onChange={(e, val) => setRole(val)}
+          options={[
+            { value: 'admin', label: 'Administrator' },
+            { value: 'editor', label: 'Editor' },
+            { value: 'viewer', label: 'Viewer' },
+          ]}
+        />
+
+        <Button type="submit">Submit</Button>
+      </Stack>
+    </form>
+  );
+}
+```
+
+### Filter Select
+
+```tsx
+function ProductFilter({ onFilterChange }) {
+  const [category, setCategory] = useState('all');
+  const [sortBy, setSortBy] = useState('newest');
+
+  useEffect(() => {
+    onFilterChange({ category, sortBy });
+  }, [category, sortBy]);
+
+  return (
+    <Stack direction="row" spacing={2}>
+      <Select
+        label="Category"
+        size="sm"
+        value={category}
+        onChange={(e, val) => setCategory(val)}
+        options={[
+          { value: 'all', label: 'All Categories' },
+          { value: 'electronics', label: 'Electronics' },
+          { value: 'clothing', label: 'Clothing' },
+          { value: 'home', label: 'Home & Garden' },
+        ]}
+      />
+
+      <Select
+        label="Sort By"
+        size="sm"
+        value={sortBy}
+        onChange={(e, val) => setSortBy(val)}
+        options={[
+          { value: 'newest', label: 'Newest First' },
+          { value: 'price-low', label: 'Price: Low to High' },
+          { value: 'price-high', label: 'Price: High to Low' },
+          { value: 'popular', label: 'Most Popular' },
+        ]}
+      />
+    </Stack>
+  );
+}
+```
+
+### Multiple Select with Tags
+
+```tsx
+function TagSelect() {
+  const [selectedTags, setSelectedTags] = useState([]);
+
+  const tagOptions = [
+    { value: 'urgent', label: 'Urgent' },
+    { value: 'feature', label: 'Feature' },
+    { value: 'bug', label: 'Bug' },
+    { value: 'enhancement', label: 'Enhancement' },
+    { value: 'documentation', label: 'Documentation' },
+  ];
+
+  return (
+    <Select
+      label="Tags"
+      multiple
+      value={selectedTags}
+      onChange={(e, val) => setSelectedTags(val)}
+      options={tagOptions}
+      placeholder="Select tags..."
+    />
+  );
+}
+```
+
+### Dependent Selects
+
+```tsx
+function LocationSelect() {
+  const [country, setCountry] = useState('');
+  const [city, setCity] = useState('');
+
+  const cities = useMemo(() => {
+    if (!country) return [];
+    return getCitiesByCountry(country);
+  }, [country]);
+
+  return (
+    <Stack spacing={2}>
+      <Select
+        label="Country"
+        value={country}
+        onChange={(e, val) => {
+          setCountry(val);
+          setCity(''); // Reset city when country changes
+        }}
+        options={countries}
+      />
+
+      <Select
+        label="City"
+        value={city}
+        onChange={(e, val) => setCity(val)}
+        options={cities}
+        disabled={!country}
+        placeholder={country ? 'Select city' : 'Select country first'}
+      />
+    </Stack>
+  );
+}
+```
+
+### With Custom Option Rendering
+
+```tsx
+function UserSelect() {
+  const userOptions = [
+    { value: 'user1', label: 'John Doe', secondaryText: 'john@example.com' },
+    { value: 'user2', label: 'Jane Smith', secondaryText: 'jane@example.com' },
+    { value: 'user3', label: 'Bob Johnson', secondaryText: 'bob@example.com' },
+  ];
+
+  return (
+    <Select
+      label="Assign to"
+      options={userOptions}
+      placeholder="Select a user..."
+    />
+  );
+}
+```
+
+## Props and Customization
+
+### Key Props
+
+| Prop           | Type                                                           | Default      | Description                     |
+| -------------- | -------------------------------------------------------------- | ------------ | ------------------------------- |
+| `options`      | `Option[]`                                                     | `[]`         | Array of options to display     |
+| `value`        | `T \| T[]`                                                     | -            | Selected value(s) (controlled)  |
+| `defaultValue` | `T \| T[]`                                                     | -            | Default value (uncontrolled)    |
+| `onChange`     | `function`                                                     | -            | Callback when selection changes |
+| `multiple`     | `boolean`                                                      | `false`      | Allow multiple selections       |
+| `label`        | `string`                                                       | -            | Label text above the Select     |
+| `helperText`   | `string`                                                       | -            | Helper text below the Select    |
+| `error`        | `boolean`                                                      | `false`      | Show error state                |
+| `required`     | `boolean`                                                      | `false`      | Mark as required                |
+| `disabled`     | `boolean`                                                      | `false`      | Disable the Select              |
+| `placeholder`  | `string`                                                       | -            | Placeholder text                |
+| `variant`      | `'plain' \| 'outlined' \| 'soft' \| 'solid'`                   | `'outlined'` | Visual style                    |
+| `color`        | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | -            | Color scheme                    |
+| `size`         | `'sm' \| 'md' \| 'lg'`                                         | `'md'`       | Component size                  |
+
+### Option Type
+
+```tsx
+interface Option {
+  value: string | number;
+  label: string;
+  secondaryText?: string;
+  disabled?: boolean;
+}
+```
+
+### Numeric Values
+
+Select supports both string and numeric values:
+
+```tsx
+<Stack spacing={4}>
+  <Select defaultValue={1} options={numericOptions} />
+  <Select defaultValue={1} variant="plain" options={numericOptions} />
+  <Select defaultValue={1} variant="soft" options={numericOptions} />
+  <Select defaultValue={1} variant="solid" options={numericOptions} />
+</Stack>
+```
+
+```tsx
+const numericOptions = [
+  { value: 1, label: 'Option 1' },
+  { value: 2, label: 'Option 2' },
+  { value: 3, label: 'Option 3' },
+];
+
+<Select options={numericOptions} defaultValue={1} />
+```
+
+### Custom Styling
+
+```tsx
+<Select
+  options={options}
+  sx={{
+    minWidth: 200,
+    '& .MuiSelect-button': {
+      borderRadius: 'xl',
+    },
+  }}
+/>
+```
+
+## Accessibility
+
+Select components follow accessibility best practices:
+
+### ARIA Attributes
+
+- Uses native listbox role with proper ARIA attributes
+- `aria-labelledby` connects to the label
+- `aria-describedby` connects to helper text
+- `aria-required` when required prop is true
+- `aria-invalid` when error prop is true
+
+### Keyboard Navigation
+
+- **Tab**: Focus the Select
+- **Enter/Space**: Open the dropdown
+- **Arrow Up/Down**: Navigate through options
+- **Home/End**: Jump to first/last option
+- **Enter**: Select the focused option
+- **Escape**: Close the dropdown
+
+### Screen Reader Support
+
+```tsx
+<Select
+  label="Country"
+  helperText="Select your country of residence"
+  options={countries}
+  aria-label="Country selection"
+/>
+```
+
+### Form Association
+
+```tsx
+<FormControl required error={hasError}>
+  <FormLabel>Country</FormLabel>
+  <Select options={countries} />
+  <FormHelperText>{hasError ? 'Please select a country' : 'Required field'}</FormHelperText>
+</FormControl>
+```
+
+## Best Practices
+
+### ✅ Do
+
+1. **Use clear labels**: Labels should clearly describe what the user is selecting
+
+```tsx
+// ✅ Good: Clear, specific label
+<Select label="Preferred contact method" options={contactMethods} />
+
+// ❌ Bad: Vague label
+<Select label="Select" options={contactMethods} />
+```
+
+2. **Provide meaningful option labels**: Options should be easy to understand
+
+```tsx
+// ✅ Good: Descriptive options
+{ value: 'express', label: 'Express Shipping (1-2 days)' }
+
+// ❌ Bad: Cryptic options
+{ value: 'exp', label: 'EXP' }
+```
+
+3. **Order options logically**: Alphabetically, by frequency, or by importance
+
+4. **Include a placeholder**: Help users understand what to select
+
+```tsx
+<Select placeholder="Select a country..." options={countries} />
+```
+
+5. **Use helper text**: Provide additional context when needed
+
+```tsx
+<Select
+  label="Timezone"
+  helperText="Select the timezone for your reports"
+  options={timezones}
+/>
+```
+
+### ❌ Don't
+
+1. **Don't use for actions**: Select is for data, not navigation or actions
+
+```tsx
+// ❌ Bad: Using Select for actions
+<Select options={[
+  { value: 'edit', label: 'Edit' },
+  { value: 'delete', label: 'Delete' },
+]} />
+
+// ✅ Good: Use Dropdown for actions
+<Dropdown>
+  <MenuButton>Actions</MenuButton>
+  <Menu>
+    <MenuItem onClick={handleEdit}>Edit</MenuItem>
+    <MenuItem onClick={handleDelete}>Delete</MenuItem>
+  </Menu>
+</Dropdown>
+```
+
+2. **Don't disable without explanation**: If options are unavailable, explain why
+
+3. **Don't use with very few options**: Consider RadioGroup for 2-4 options
+
+4. **Don't use with many options without search**: Use Autocomplete for 20+ options
+
+## Performance Considerations
+
+### Large Option Lists
+
+For lists with many options, consider:
+
+1. **Pagination or virtual scrolling**: For very large lists
+2. **Autocomplete**: When users need to search through options
+3. **Lazy loading**: Load options on demand
+
+```tsx
+// For many options, use Autocomplete instead
+<Autocomplete
+  options={largeOptionList}
+  getOptionLabel={(option) => option.label}
+  renderInput={(params) => <Input {...params} label="Search..." />}
+/>
+```
+
+### Controlled vs Uncontrolled
+
+Use controlled mode only when necessary:
+
+```tsx
+// Uncontrolled - simpler, better performance
+<Select defaultValue="option1" options={options} />
+
+// Controlled - when you need to sync with other state
+const [value, setValue] = useState('option1');
+<Select value={value} onChange={(e, val) => setValue(val)} options={options} />
+```
+
+### Memoize Options
+
+When options are computed, memoize them:
+
+```tsx
+const options = useMemo(() =>
+  data.map(item => ({
+    value: item.id,
+    label: item.name,
+  })),
+[data]);
+
+<Select options={options} />
+```
+
+Select is a fundamental form component that provides a clean interface for choosing from predefined options. Use it appropriately to create intuitive forms and ensure users can easily make selections.