# Core/SelectField - Design

## Anatomy

1. **Label**: describes the field and carries the required marker when needed.
2. **Trigger**: matches Capra text-input sizing and state treatments.
3. **Popover**: contains the option list and optional search field.
4. **ListBox items**: support single-select rows or multi-select rows with checkmarks.
5. **Sections**: optional grouped options with a non-selectable header label.

## Properties

### Layout

Use `layout="vertical"` by default. Use `layout="horizontal"` only when space is constrained.

### Multiple Selection

For multi-select fields, selected options appear as removable tags inside the trigger. Tags wrap onto additional lines when they exceed the field width, and selected rows show a checkmark in the popover.

### Search

Enable `canSearch` for longer option lists. Search filters the visible options inside the popover without changing the trigger layout. When nothing matches, the popover shows "No results" so the list never appears empty.

### Sections

Larger option lists can be organized into smaller groups using sections. Each section has a header to label the grouping. Pass `items` with nested `children` to build sections from data, or wrap static options in `SelectField.Section` with a `SelectField.Header`.

## States

* Match the standard input states: default, hover, focus, disabled, placeholder, warning, and danger.
* `appearance="danger"` drives the invalid visual state and helper text treatment.
* Small and medium sizes align with `TextInput`.

## Behavior

* Use `SelectField` for fixed option sets, especially when the option count is greater than about five.
* Prefer `RadioGroup` when the user should see all mutually exclusive choices at once.
* Prefer `AutocompleteField` when freeform typing or custom values are required.

## Accessibility

### Keyboard interaction

| Key                          | Function                                                                                                                                                                                                                                                                             |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Tab` / `Shift + Tab`        | Moves focus into the multiselect TagGroup (first selected tag) or the open button, then to the next or previous focusable element. Remove buttons are not sequential tab stops. If the option list is open, these keys are ignored.                                                  |
| `Left Arrow` / `Right Arrow` | In multiple-select mode with the TagGroup focused: moves focus between selected tags.                                                                                                                                                                                                |
| `Delete` / `Backspace`       | In multiple-select mode with a selected tag focused: removes that tag.                                                                                                                                                                                                               |
| `Down Arrow` / `Up Arrow`    | If the option list is closed and the open button has focus: opens the list and moves focus to the selected item (the first selected item in multiple-select mode), or the first/last item when nothing is selected. If the list is open: moves focus to the next or previous option. |
| `Enter` / `Space`            | If the option list is closed: opens the option list (from the open button). If the list is open: selects the focused option. In single-select mode the list closes after selection; in multiple-select mode the list stays open.                                                     |
| `Esc`                        | If the option list is open: closes the list and returns focus to the select trigger.                                                                                                                                                                                                 |

While the option list is open, focus stays inside the popover in both selection modes.

In multiple-select mode, selected values use React Aria’s `TagGroup` in the trigger (styled to match Capra Tag). Keyboard behavior follows TagGroup defaults: arrows move between tags; Delete/Backspace removes; clicking the remove control also removes.

### Labeling

All select fields require a label. Provide a visible `label` prop when possible. When a visible label is not spatially associated with the trigger, use `aria-label` or `aria-labelledby`.

### Focus treatment

* The trigger uses the Capra 2px focus outline (`token('border.focus')`).
* List options show a keyboard focus ring on the active row; the popover container suppresses the browser default panel outline (same pattern as `Menu`).
* Warning and danger icons in the trigger are decorative (`aria-hidden`); invalid state is conveyed with `aria-invalid` on the trigger.