@ceed/ads 1.23.3 → 1.23.4

package/dist/components/inputs/Select.md

@@ -2,7 +2,9 @@
 
 ## 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.
+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.
 
 ```tsx
 <Select options={options} />
@@ -24,20 +26,20 @@ The Select component is a form input that allows users to choose one or multiple
 | onChange       | —           | —       |
 | options        | —           | options |
 
-> ⚠️ **Don't Confuse Select with Dropdown** ⚠️
+> **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
+> - **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:
+> Choosing 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
+> - 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**
+> **Use built-in form props**
 >
-> This component natively supports form elements such as `label` and `helperText` props.
+> 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.
 
 ## Usage
@@ -62,19 +64,9 @@ function MyComponent() {
 }
 ```
 
-## Examples
-
-### Basic Select
-
-The default Select with a list of options.
-
-```tsx
-<Select options={options} />
-```
-
-### Variants
+## Variants
 
-Select supports different visual styles.
+Select supports four visual styles: `outlined` (default), `plain`, `soft`, and `solid`.
 
 ```tsx
 <Stack spacing={4}>
@@ -85,9 +77,16 @@ Select supports different visual styles.
 </Stack>
 ```
 
-### Sizes
+```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
 
-Select comes in different sizes.
+Three sizes are available: `sm`, `md` (default), and `lg`.
 
 ```tsx
 <Stack spacing={4}>
@@ -97,9 +96,15 @@ Select comes in different sizes.
 </Stack>
 ```
 
-### Colors
+```tsx
+<Select options={options} defaultValue="dog" size="sm" />
+<Select options={options} defaultValue="dog" size="md" />
+<Select options={options} defaultValue="dog" size="lg" />
+```
+
+## Colors
 
-Apply semantic colors to Select.
+Apply semantic colors to communicate intent or state.
 
 ```tsx
 <Stack spacing={4}>
@@ -111,9 +116,17 @@ Apply semantic colors to Select.
 </Stack>
 ```
 
-### With Decorators
+```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" />
+```
 
-Add icons or badges to the Select.
+## Decorators
+
+Use `startDecorator` and `endDecorator` to add icons, badges, or other elements beside the select trigger.
 
 ```tsx
 <Select placeholder="Select a pet…" startDecorator={<FavoriteBorder />} endDecorator={<Chip size="sm" color="danger" variant="soft">
@@ -123,9 +136,24 @@ width: 240
 }} options={options} />
 ```
 
-### With Label
+```tsx
+import FavoriteBorder from '@mui/icons-material/FavoriteBorder';
+import { Chip } from '@ceed/ads';
 
-Select with an associated 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.
 
 ```tsx
 <>
@@ -133,19 +161,26 @@ Select with an associated label.
 </>
 ```
 
-### With Helper Text
-
-Add helper text for additional context.
-
 ```tsx
 <>
   <Select label="Select" helperText="I'm helper text" defaultValue="dog" options={options} />
 </>
 ```
 
-### Error State
+```tsx
+<Select label="Pet" options={options} defaultValue="dog" />
 
-Show validation errors.
+<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.
 
 ```tsx
 <>
@@ -153,9 +188,18 @@ Show validation errors.
 </>
 ```
 
-### Form Control
+```tsx
+<Select
+  label="Pet"
+  error
+  helperText="This field is required"
+  options={options}
+/>
+```
+
+## Form Control
 
-Complete form integration with label and helper text.
+Combining `label`, `helperText`, and `error` produces a complete form field. Here is a normal field next to one with an error.
 
 ```tsx
 <>
@@ -164,9 +208,9 @@ Complete form integration with label and helper text.
 </>
 ```
 
-### Required Field
+## Required Field
 
-Mark the Select as required.
+Set `required` to mark the field as required. An asterisk is added to the label automatically.
 
 ```tsx
 <Select
@@ -177,9 +221,18 @@ Mark the Select as required.
 />
 ```
 
-### Multiple Selection
+```tsx
+<Select
+  label="Pet"
+  helperText="This field is required"
+  required
+  options={options}
+/>
+```
+
+## Multiple Selection
 
-Allow selecting multiple options.
+Set `multiple` to allow selecting more than one option. The value becomes an array.
 
 ```tsx
 <Select
@@ -191,9 +244,18 @@ Allow selecting multiple options.
 />
 ```
 
-### Controlled Select
+```tsx
+<Select
+  label="Pets"
+  multiple
+  defaultValue={['dog']}
+  options={options}
+/>
+```
+
+## Controlled Select
 
-Programmatically control the selected value.
+Use the `value` and `onChange` props for controlled behavior when you need to synchronize the selected value with other state.
 
 ```tsx
 <div>
@@ -212,9 +274,20 @@ Programmatically control the selected value.
 </div>
 ```
 
-### Disabled Options
+```tsx
+const [value, setValue] = useState('dog');
 
-Individual options can be disabled.
+<Select
+  label="Pet"
+  value={value}
+  onChange={(event, newValue) => setValue(newValue)}
+  options={options}
+/>
+```
+
+## Disabled Options
+
+Individual options can be disabled by setting `disabled: true` on the option object.
 
 ```tsx
 <Select
@@ -227,9 +300,20 @@ Individual options can be disabled.
 />
 ```
 
-### Options with Secondary Text
+```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
 
-Display additional information for each option.
+Add a `secondaryText` field to display supplementary information below each option label. The secondary text size scales proportionally with the component `size`.
 
 ```tsx
 <Stack spacing={4} direction="row" alignItems="flex-start">
@@ -245,58 +329,76 @@ Display additional information for each option.
 </Stack>
 ```
 
-## When to Use
+```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' },
+];
+
+<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.
+
+```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>
+```
 
-### ❌ When Not to Use
+```tsx
+const numericOptions = [
+  { value: 1, label: 'Option 1' },
+  { value: 2, label: 'Option 2' },
+  { value: 3, label: 'Option 3' },
+];
 
-- **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
+<Select options={numericOptions} defaultValue={1} />
+```
 
 ## Common Use Cases
 
-### Form with Select
+### Form with Validation
 
 ```tsx
+import { useState } from 'react';
+import { Select, Button, Stack } from '@ceed/ads';
+
 function UserForm() {
-  const [country, setCountry] = useState('');
-  const [role, setRole] = useState('');
+  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
+    }
+  };
 
   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>
@@ -304,9 +406,11 @@ function UserForm() {
 }
 ```
 
-### Filter Select
+### Filter Bar
 
 ```tsx
+import { Select, Stack } from '@ceed/ads';
+
 function ProductFilter({ onFilterChange }) {
   const [category, setCategory] = useState('all');
   const [sortBy, setSortBy] = useState('newest');
@@ -326,10 +430,8 @@ 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"
@@ -339,7 +441,6 @@ 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>
@@ -347,39 +448,15 @@ function ProductFilter({ onFilterChange }) {
 }
 ```
 
-### 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
+import { useState, useMemo } from 'react';
+import { Select, Stack } from '@ceed/ads';
+
 function LocationSelect() {
-  const [country, setCountry] = useState('');
-  const [city, setCity] = useState('');
+  const [country, setCountry] = useState<string | null>(null);
+  const [city, setCity] = useState<string | null>(null);
 
   const cities = useMemo(() => {
     if (!country) return [];
@@ -393,269 +470,83 @@ function LocationSelect() {
         value={country}
         onChange={(e, val) => {
           setCountry(val);
-          setCity(''); // Reset city when country changes
+          setCity(null);
         }}
         options={countries}
+        placeholder="Select a country"
       />
-
       <Select
         label="City"
         value={city}
         onChange={(e, val) => setCity(val)}
         options={cities}
         disabled={!country}
-        placeholder={country ? 'Select city' : 'Select country first'}
+        placeholder={country ? 'Select a city' : 'Select a 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
+1. **Use clear, specific labels.** The label should describe exactly what the user is choosing.
 
 ```tsx
-// ✅ Good: Clear, specific label
+// ✅ Good
 <Select label="Preferred contact method" options={contactMethods} />
 
-// ❌ Bad: Vague label
+// ❌ Bad
 <Select label="Select" options={contactMethods} />
 ```
 
-2. **Provide meaningful option labels**: Options should be easy to understand
+2. **Provide meaningful option text.** Each option label should be immediately understandable.
 
 ```tsx
-// ✅ Good: Descriptive options
+// ✅ Good
 { value: 'express', label: 'Express Shipping (1-2 days)' }
 
-// ❌ Bad: Cryptic options
+// ❌ Bad
 { 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
+3. **Do not use Select for actions.** Select is for data input. For action menus (Edit, Delete, etc.), use Dropdown with Menu.
 
 ```tsx
+// ✅ Good: Select for data
 <Select
-  label="Timezone"
-  helperText="Select the timezone for your reports"
-  options={timezones}
+  label="Country"
+  options={countries}
 />
-```
-
-### ❌ 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..." />}
+// ❌ Bad: Select for actions
+<Select
+  options={[
+    { value: 'edit', label: 'Edit' },
+    { value: 'delete', label: 'Delete' },
+  ]}
 />
 ```
 
-### Controlled vs Uncontrolled
+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.
 
-Use controlled mode only when necessary:
+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.
 
 ```tsx
-// Uncontrolled - simpler, better performance
-<Select defaultValue="option1" options={options} />
+// ✅ Good
+<Select label="Timezone" helperText="Used for report scheduling" options={timezones} />
 
-// Controlled - when you need to sync with other state
-const [value, setValue] = useState('option1');
-<Select value={value} onChange={(e, val) => setValue(val)} options={options} />
+// ❌ Bad
+<FormControl>
+  <FormLabel>Timezone</FormLabel>
+  <Select options={timezones} />
+  <FormHelperText>Used for report scheduling</FormHelperText>
+</FormControl>
 ```
 
-### 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} />
-```
+## Accessibility
 
-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.
+- **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.