# Selects

All select components collect user input from a list of options. Choose based on how many options can be selected and whether the list is domain-specific.

## Decision Tree

```
Selecting from a list of options?
├── Single selection?
│   ├── General purpose → Select
│   ├── Countries → CountrySelect
│   ├── Timezones → TimezoneSelector
│   ├── From a column header → HeaderSelect
│   └── Single date → DatePicker
└── Multiple selection?
    ├── General purpose → MultiSelect
    ├── Countries / markets → MarketSelector
    └── Date range → DateRangePicker
```

---

## Select

Single-option dropdown from a list.

```tsx
import { Select } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `options` | `SelectOption[]` | required | Array of options |
| `onChange` | function | — | Called on selection |
| `selectedValue` | `SelectOption` | — | Controlled selected value |
| `defaultValue` | `SelectOption` | — | Uncontrolled initial value |
| `placeholder` | string | `'Select a value'` | Placeholder text |
| `disabled` | boolean | — | Disables the select |
| `compact` | boolean | — | Compact display variant |
| `hideClearButton` | boolean | — | Hides the clear (×) button |
| `hideFilter` | boolean | — | Hides the search filter input inside the dropdown |
| `name` | string | — | HTML form field name |

### SelectOption Shape

```ts
{
  value: string | number,
  label: string,
  subtitle?: string,    // secondary text under label
  disabled?: boolean,
}
```

### Example

```tsx
<Select
  options={[
    { value: 'rock', label: 'Rock' },
    { value: 'pop', label: 'Pop' },
  ]}
  placeholder="Select genre"
  onChange={option => setGenre(option?.value)}
/>
```

---

## MultiSelect

Allows selecting multiple options simultaneously.

```tsx
import { MultiSelect } from '@theorchard/suite-components';
```

Inherits all props from `Select`. The `onChange` callback receives an array of selected options.

### Key Additional Props

| Prop | Type | Description |
|---|---|---|
| `requireApply` | boolean | Shows Apply button — selection only commits on confirm |
| `showListModes` | boolean | Shows list mode toggles (include/exclude) |
| `showExcludeModeToggle` | boolean | Shows exclude-mode toggle |
| `quickSelections` | array | Predefined quick-select presets |

### Example

```tsx
<MultiSelect
  options={territories}
  selectedValue={selectedTerritories}
  onChange={setSelectedTerritories}
  placeholder="Select territories"
/>
```

---

## HeaderSelect

Select triggered from a table column header. Inherits all `Select` functionality.

```tsx
import { HeaderSelect } from '@theorchard/suite-components';
```

Use only inside table column headers, not as a standalone form control.

---

## CountrySelect

Single-country selector with flag icons and country search.

```tsx
import { CountrySelect } from '@theorchard/suite-components';
```

Use instead of a generic `Select` when the domain is specifically countries.

---

## MarketSelector

Multi-country selector organised by market groupings.

```tsx
import { MarketSelector } from '@theorchard/suite-components';
```

Use for territory/market selection with multi-select capability. Replaces building a `MultiSelect` with a custom countries list.

---

## TimezoneSelector

Single-timezone dropdown with timezone search.

```tsx
import { TimezoneSelector } from '@theorchard/suite-components';
```

---

## DatePicker

Calendar-based single date selector.

```tsx
import { DatePicker } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Description |
|---|---|---|
| `value` | `Date` | Controlled selected date |
| `onChange` | function | Called with selected `Date` |
| `minDate` | `Date` | Minimum selectable date |
| `maxDate` | `Date` | Maximum selectable date |
| `disabled` | boolean | Disables the picker |

---

## DateRangePicker

Calendar-based date-range selector with start and end date.

```tsx
import { DateRangePicker } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Description |
|---|---|---|
| `startDate` | `Date` | Start of range |
| `endDate` | `Date` | End of range |
| `onChange` | function | Called with `{ startDate, endDate }` |

## Common Mistakes

- Do NOT use `Select` for countries — use `CountrySelect` or `MarketSelector`.
- Do NOT use `Select` for timezones — use `TimezoneSelector`.
- Do NOT use a raw `<select>` element — always use `Select` or a domain-specific variant.
- Do NOT use deprecated `Dropdown` or `SearchDropdown` — use `Select` with `filterPlaceholder` prop for searchable behaviour.