@ceed/ads 1.29.1 → 1.30.0-next.1

package/dist/components/inputs/Select.md

@@ -2,9 +2,7 @@
 
 ## 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 picking values within forms, filters, and configuration settings.
-
-Select accepts options as an array of objects (with `value`, `label`, and optional `secondaryText` / `disabled` fields) or as simple string/number arrays. It wraps the underlying select element with built-in `FormControl`, `FormLabel`, and `FormHelperText` so you can compose complete form fields with a single component.
+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} />
@@ -26,21 +24,16 @@ Select accepts options as an array of objects (with `value`, `label`, and option
 | 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.
+> ⚠️ **Don't Confuse Select with Dropdown** ⚠️
 >
-> Choosing the right component:
+> - **Select**: For form value selection - the selected value becomes form data
+> - **Dropdown**: For menus and action lists - triggers actions or navigation
 >
-> - Fewer than 5 options -- consider RadioButton or RadioGroup
-> - More than 20 options -- consider Autocomplete with search
-> - Actions / navigation -- use Dropdown with Menu
-
-> **Use built-in form props**
+> Choose the right component:
 >
-> This component natively supports `label` and `helperText` props.
-> When building forms, use these built-in props instead of manually composing labels and helper text with Typography.
+> - Less than 5 options → Consider RadioButton or RadioGroup
+> - More than 20 options → Consider Autocomplete with search
+> - Actions/navigation → Use Dropdown with Menu
 
 ## Usage
 
@@ -64,9 +57,19 @@ function MyComponent() {
 }
 ```
 
-## Variants
+## Examples
+
+### Basic Select
+
+The default Select with a list of options.
+
+```tsx
+<Select options={options} />
+```
+
+### Variants
 
-Select supports four visual styles: `outlined` (default), `plain`, `soft`, and `solid`.
+Select supports different visual styles.
 
 ```tsx
 <Stack spacing={4}>
@@ -77,16 +80,9 @@ Select supports four visual styles: `outlined` (default), `plain`, `soft`, and `
 </Stack>
 ```
 
-```tsx
-<Select options={options} defaultValue="dog" />
-<Select options={options} defaultValue="dog" variant="plain" />
-<Select options={options} defaultValue="dog" variant="soft" />
-<Select options={options} defaultValue="dog" variant="solid" />
-```
-
-## Sizes
+### Sizes
 
-Three sizes are available: `sm`, `md` (default), and `lg`.
+Select comes in different sizes.
 
 ```tsx
 <Stack spacing={4}>
@@ -96,15 +92,9 @@ Three sizes are available: `sm`, `md` (default), and `lg`.
 </Stack>
 ```
 
-```tsx
-<Select options={options} defaultValue="dog" size="sm" />
-<Select options={options} defaultValue="dog" size="md" />
-<Select options={options} defaultValue="dog" size="lg" />
-```
-
-## Colors
+### Colors
 
-Apply semantic colors to communicate intent or state.
+Apply semantic colors to Select.
 
 ```tsx
 <Stack spacing={4}>
@@ -116,17 +106,9 @@ Apply semantic colors to communicate intent or state.
 </Stack>
 ```
 
-```tsx
-<Select options={options} defaultValue="dog" color="primary" />
-<Select options={options} defaultValue="dog" color="neutral" />
-<Select options={options} defaultValue="dog" color="success" />
-<Select options={options} defaultValue="dog" color="danger" />
-<Select options={options} defaultValue="dog" color="warning" />
-```
+### With Decorators
 
-## Decorators
-
-Use `startDecorator` and `endDecorator` to add icons, badges, or other elements beside the select trigger.
+Add icons or badges to the Select.
 
 ```tsx
 <Select placeholder="Select a pet…" startDecorator={<FavoriteBorder />} endDecorator={<Chip size="sm" color="danger" variant="soft">
@@ -136,24 +118,9 @@ width: 240
 }} options={options} />
 ```
 
-```tsx
-import FavoriteBorder from '@mui/icons-material/FavoriteBorder';
-import { Chip } from '@ceed/ads';
+### With Label
 
-<Select
-  placeholder="Select a pet..."
-  startDecorator={<FavoriteBorder />}
-  endDecorator={
-    <Chip size="sm" color="danger" variant="soft">+5</Chip>
-  }
-  options={options}
-  sx={{ width: 240 }}
-/>
-```
-
-## Label and Helper Text
-
-The `label` prop renders a form label above the select. The `helperText` prop renders descriptive text below it. Both are built into the component so you do not need to compose them separately.
+Select with an associated label.
 
 ```tsx
 <>
@@ -161,26 +128,19 @@ The `label` prop renders a form label above the select. The `helperText` prop re
 </>
 ```
 
+### With Helper Text
+
+Add helper text for additional context.
+
 ```tsx
 <>
   <Select label="Select" helperText="I'm helper text" defaultValue="dog" options={options} />
 </>
 ```
 
-```tsx
-<Select label="Pet" options={options} defaultValue="dog" />
+### Error State
 
-<Select
-  label="Pet"
-  helperText="Choose your favorite animal"
-  options={options}
-  defaultValue="dog"
-/>
-```
-
-## Error State
-
-Set `error` to `true` to visually indicate a validation error. Combine with `helperText` to display an error message.
+Show validation errors.
 
 ```tsx
 <>
@@ -188,18 +148,9 @@ Set `error` to `true` to visually indicate a validation error. Combine with `hel
 </>
 ```
 
-```tsx
-<Select
-  label="Pet"
-  error
-  helperText="This field is required"
-  options={options}
-/>
-```
-
-## Form Control
+### Form Control
 
-Combining `label`, `helperText`, and `error` produces a complete form field. Here is a normal field next to one with an error.
+Complete form integration with label and helper text.
 
 ```tsx
 <>
@@ -208,9 +159,9 @@ Combining `label`, `helperText`, and `error` produces a complete form field. Her
 </>
 ```
 
-## Required Field
+### Required Field
 
-Set `required` to mark the field as required. An asterisk is added to the label automatically.
+Mark the Select as required.
 
 ```tsx
 <Select
@@ -221,18 +172,9 @@ Set `required` to mark the field as required. An asterisk is added to the label
 />
 ```
 
-```tsx
-<Select
-  label="Pet"
-  helperText="This field is required"
-  required
-  options={options}
-/>
-```
-
-## Multiple Selection
+### Multiple Selection
 
-Set `multiple` to allow selecting more than one option. The value becomes an array.
+Allow selecting multiple options.
 
 ```tsx
 <Select
@@ -244,18 +186,9 @@ Set `multiple` to allow selecting more than one option. The value becomes an arr
 />
 ```
 
-```tsx
-<Select
-  label="Pets"
-  multiple
-  defaultValue={['dog']}
-  options={options}
-/>
-```
-
-## Controlled Select
+### Controlled Select
 
-Use the `value` and `onChange` props for controlled behavior when you need to synchronize the selected value with other state.
+Programmatically control the selected value.
 
 ```tsx
 <div>
@@ -274,20 +207,9 @@ Use the `value` and `onChange` props for controlled behavior when you need to sy
 </div>
 ```
 
-```tsx
-const [value, setValue] = useState('dog');
-
-<Select
-  label="Pet"
-  value={value}
-  onChange={(event, newValue) => setValue(newValue)}
-  options={options}
-/>
-```
-
-## Disabled Options
+### Disabled Options
 
-Individual options can be disabled by setting `disabled: true` on the option object.
+Individual options can be disabled.
 
 ```tsx
 <Select
@@ -300,20 +222,9 @@ Individual options can be disabled by setting `disabled: true` on the option obj
 />
 ```
 
-```tsx
-const options = [
-  { value: 'dog', label: 'Dog', disabled: true },
-  { value: 'cat', label: 'Cat' },
-  { value: 'fish', label: 'Fish', disabled: true },
-  { value: 'bird', label: 'Bird' },
-];
-
-<Select label="Pet" options={options} defaultValue="dog" />
-```
-
-## Options with Secondary Text
+### Options with Secondary Text
 
-Add a `secondaryText` field to display supplementary information below each option label. The secondary text size scales proportionally with the component `size`.
+Display additional information for each option.
 
 ```tsx
 <Stack spacing={4} direction="row" alignItems="flex-start">
@@ -329,76 +240,58 @@ Add a `secondaryText` field to display supplementary information below each opti
 </Stack>
 ```
 
-```tsx
-const userOptions = [
-  { value: 'emily', label: 'Emily Carter', secondaryText: '(415) 555-0198' },
-  { value: 'daniel', label: 'Daniel Kim', secondaryText: '(212) 555-0421' },
-  { value: 'sophia', label: 'Sophia Martinez', secondaryText: '(646) 555-0734' },
-];
+## When to Use
 
-<Select placeholder="Select a contact" options={userOptions} />
-```
+### ✅ Good Use Cases
 
-## Numeric Values
+- **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
 
-Select supports both string and numeric option values. When using numeric values, TypeScript infers the correct type automatically.
+### ❌ When Not to Use
 
-```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} />
-```
+- **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 Validation
+### Form with Select
 
 ```tsx
-import { useState } from 'react';
-import { Select, Button, Stack } from '@ceed/ads';
-
 function UserForm() {
-  const [role, setRole] = useState<string | null>(null);
-  const [submitted, setSubmitted] = useState(false);
-
-  const handleSubmit = (e: React.FormEvent) => {
-    e.preventDefault();
-    setSubmitted(true);
-    if (role) {
-      // submit form
-    }
-  };
+  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)}
-          error={submitted && !role}
-          helperText={submitted && !role ? 'Please select a role' : undefined}
           options={[
             { value: 'admin', label: 'Administrator' },
             { value: 'editor', label: 'Editor' },
             { value: 'viewer', label: 'Viewer' },
           ]}
-          placeholder="Select a role..."
         />
+
         <Button type="submit">Submit</Button>
       </Stack>
     </form>
@@ -406,11 +299,9 @@ function UserForm() {
 }
 ```
 
-### Filter Bar
+### Filter Select
 
 ```tsx
-import { Select, Stack } from '@ceed/ads';
-
 function ProductFilter({ onFilterChange }) {
   const [category, setCategory] = useState('all');
   const [sortBy, setSortBy] = useState('newest');
@@ -430,8 +321,10 @@ function ProductFilter({ onFilterChange }) {
           { value: 'all', label: 'All Categories' },
           { value: 'electronics', label: 'Electronics' },
           { value: 'clothing', label: 'Clothing' },
+          { value: 'home', label: 'Home & Garden' },
         ]}
       />
+
       <Select
         label="Sort By"
         size="sm"
@@ -441,6 +334,7 @@ function ProductFilter({ onFilterChange }) {
           { 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>
@@ -448,15 +342,39 @@ function ProductFilter({ onFilterChange }) {
 }
 ```
 
-### Dependent Selects
+### Multiple Select with Tags
 
 ```tsx
-import { useState, useMemo } from 'react';
-import { Select, Stack } from '@ceed/ads';
+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<string | null>(null);
-  const [city, setCity] = useState<string | null>(null);
+  const [country, setCountry] = useState('');
+  const [city, setCity] = useState('');
 
   const cities = useMemo(() => {
     if (!country) return [];
@@ -470,83 +388,269 @@ function LocationSelect() {
         value={country}
         onChange={(e, val) => {
           setCountry(val);
-          setCity(null);
+          setCity(''); // Reset city when country changes
         }}
         options={countries}
-        placeholder="Select a country"
       />
+
       <Select
         label="City"
         value={city}
         onChange={(e, val) => setCity(val)}
         options={cities}
         disabled={!country}
-        placeholder={country ? 'Select a city' : 'Select a country first'}
+        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
 
-1. **Use clear, specific labels.** The label should describe exactly what the user is choosing.
+### ✅ Do
+
+1. **Use clear labels**: Labels should clearly describe what the user is selecting
 
 ```tsx
-// ✅ Good
+// ✅ Good: Clear, specific label
 <Select label="Preferred contact method" options={contactMethods} />
 
-// ❌ Bad
+// ❌ Bad: Vague label
 <Select label="Select" options={contactMethods} />
 ```
 
-2. **Provide meaningful option text.** Each option label should be immediately understandable.
+2. **Provide meaningful option labels**: Options should be easy to understand
 
 ```tsx
-// ✅ Good
+// ✅ Good: Descriptive options
 { value: 'express', label: 'Express Shipping (1-2 days)' }
 
-// ❌ Bad
+// ❌ Bad: Cryptic options
 { value: 'exp', label: 'EXP' }
 ```
 
-3. **Do not use Select for actions.** Select is for data input. For action menus (Edit, Delete, etc.), use Dropdown with Menu.
+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
-// ✅ Good: Select for data
 <Select
-  label="Country"
-  options={countries}
+  label="Timezone"
+  helperText="Select the timezone for your reports"
+  options={timezones}
 />
+```
 
-// ❌ Bad: Select for actions
-<Select
-  options={[
-    { value: 'edit', label: 'Edit' },
-    { value: 'delete', label: 'Delete' },
-  ]}
+### ❌ 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..." />}
 />
 ```
 
-4. **Choose the right component for the option count.** For 2--4 visible choices, use RadioGroup. For 20+ options that need searching, use Autocomplete. Select works best with roughly 5--20 options.
+### Controlled vs Uncontrolled
 
-5. **Use the built-in `label` and `helperText` props** instead of manually wrapping Select with FormControl, FormLabel, and FormHelperText. The component handles the composition and accessibility wiring internally.
+Use controlled mode only when necessary:
 
 ```tsx
-// ✅ Good
-<Select label="Timezone" helperText="Used for report scheduling" options={timezones} />
+// Uncontrolled - simpler, better performance
+<Select defaultValue="option1" options={options} />
 
-// ❌ Bad
-<FormControl>
-  <FormLabel>Timezone</FormLabel>
-  <Select options={timezones} />
-  <FormHelperText>Used for report scheduling</FormHelperText>
-</FormControl>
+// Controlled - when you need to sync with other state
+const [value, setValue] = useState('option1');
+<Select value={value} onChange={(e, val) => setValue(val)} options={options} />
 ```
 
-## Accessibility
+### 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} />
+```
 
-- **Label association**: When you use the `label` prop, the component automatically connects the label to the select element via `aria-labelledby`. Always provide a label for screen reader users.
-- **Keyboard navigation**: The select can be opened with Enter or Space, navigated with Arrow Up/Down and Home/End, confirmed with Enter, and dismissed with Escape.
-- **Error announcement**: When `error` is set, `aria-invalid` is applied. Pair it with a descriptive `helperText` so assistive technology can announce the error reason.
-- **Required state**: The `required` prop adds `aria-required` and a visible asterisk to the label, communicating the requirement both visually and programmatically.
+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.