# Select: API

## API корня

`Select` — корневой контейнер состояния для всей композиции.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean` | — | Нет | Отключён ли select. Запрещает взаимодействие и применяет стиль отключённого состояния. |
| `readOnly` | `boolean` | `false` | Нет | Если true, значение select нельзя изменить, но он остаётся фокусируемым. |
| `variant` | `SelectVariant` | `'field'` | Нет | Вариант визуального стиля элемента выбора. |
| `size` | `SelectSize` | `'md'` | Нет | Визуальный размер элемента выбора. |
| `value` | `V \| null` | — | Нет | Текущее выбранное значение (контролируемо). `null` очищает выбор, а `undefined` делает select неконтролируемым. |
| `defaultValue` | `V` | — | Нет | Значение, выбранное по умолчанию (неконтролируемо). |
| `onChangeValue` | `(value: V \| undefined) => void` | — | Нет | Колбэк, вызываемый при выборе варианта. |
| `ref` | `Ref<HTMLDivElement>` | — | Нет | Ref на корневой элемент. |
| `open` | `boolean` | — | Нет | Управляет состоянием открытия выпадающего списка Select. Если задан, Select становится контролируемым компонентом и по этому значению определяет, открыт список или закрыт. |
| `onChangeOpen` | `(open: boolean) => void` | — | Нет | Колбэк, вызываемый при изменении состояния открытия. Вызывается со следующим состоянием открытия (`true` или `false`) каждый раз, когда пользователь открывает или закрывает Select. Полезен для синхронизации состояния Select с внешней логикой. |
| `defaultOpen` | `boolean` | `false` | Нет | Задаёт начальное состояние открытия Select в неконтролируемом режиме. Применяется только при первом рендере и дальше игнорируется. |
| `typeahead` | `boolean` | `true` | Нет | Включает переход к варианту при наборе начала его подписи. |

Также принимает все атрибуты `<div>`.

## API дочерних частей

## `SelectCombobox`

Видимая поверхность триггера select.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `ref` | `Ref<HTMLButtonElement>` | — | Нет | Ref на нижележащий элемент `<button>`. Полезен для управления фокусом, позиционирования и императивного доступа. |

Также принимает все атрибуты `<button>`.

- Типичные дочерние элементы: `SelectValue`, `SelectIcon`
- Должна оставаться внутри `Select`

## `SelectValue`

Рендерит выбранное значение или плейсхолдер.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `placeholder` | `string` | — | Нет | Текст-заполнитель, который показывается, когда не выбран ни один вариант. Отображается, когда значение select пустое или undefined. После выбора значения заполнитель заменяется содержимым выбранного варианта. |
| `ref` | `Ref<HTMLSpanElement>` | — | Нет | Ref, передаваемый на корневой элемент span. |

Также принимает все атрибуты `<span>`.

- Поддерживает содержимое плейсхолдера
- Может рендерить собственные дочерние элементы для более богатого отображения выбранного значения

## `SelectIcon`

Необязательная визуальная подсказка триггера.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `size` | `IconSize` | — | Нет | Предопределённый токен размера иконки. Может быть переопределён явными шириной и высотой. |
| `ref` | `Ref<SVGSVGElement>` | — | Нет | Ref на SVG-элемент |
| `strokeWidth` | `number` | — | Нет | Толщина обводки линий и фигур SVG (в px или pt). |
| `children` | `ReactNode` | — | Нет | Содержимое иконки (обязательно). Принимает: иконки из `~/icons`; собственный встроенный SVG; компоненты иконок сторонних библиотек (например, Lucide, Tabler) |

Также принимает все HTML-атрибуты.

- Обычно рендерится в конце `SelectCombobox`
- Чисто визуальная, если намеренно не добавлено собственное взаимодействие

## `SelectListbox`

Контейнер зарегистрированных вариантов.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `ref` | `Ref<HTMLDivElement>` | — | Нет | Ref на элемент-контейнер списка. Можно использовать для императивного доступа, например для измерений. |

Также принимает все атрибуты `<div>`.

- Ожидаемые дочерние элементы: `SelectOption`
- Обычное место для ограничений прокрутки, полей поиска и собственного макета списка
- Рендерится в top layer через `popover="manual"` и сам управляет фокусом

## `SelectOption`

Выбираемый элемент списка.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `value` | `V` | — | Да | Значение этого варианта, которое передаётся в колбэк изменения при его выборе. |
| `label` | `string` | — | Нет | Простой текст варианта для поиска при наборе; используется вместо текста его содержимого. |
| `children` | `ReactNode` | — | Нет | Содержимое, отображаемое для этого варианта. Может включать текст, иконки или сложную разметку. |
| `size` | `OptionSize` | — | Нет | Размер варианта для визуальной стилизации. |
| `disabled` | `boolean` | — | Нет | Отключает весь Option. |
| `ref` | `Ref<HTMLDivElement>` | — | Нет | Ref, передаваемый на корневой div варианта. |

Также принимает все атрибуты `<div>`.

- `value` должен быть `string` или `number`
- Сам регистрируется в модели вариантов корня
- Может рендерить более богатое дочернее содержимое, но значение выбора остаётся скалярным

## `SelectHiddenSelect`

Скрытый нативный элемент select.

Также принимает все атрибуты `<select>`.

- Рекомендуется для форм
- Помогает с нативной отправкой и интеграцией с инструментами для форм

## Хуки

## `useSelectContext`

Продвинутый хук для собственных обёрток вокруг готовых частей.

Используйте его, только когда экспортируемых частей недостаточно для нужной композиции.

## Типы

| Тип | Определение | Примечания |
| --- | --- | --- |
| `SelectProps<V extends string \| number = string>` | Тип пропсов корня | Обобщённый тип значения для выбора. |
| `SelectSize` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| string` | Токен визуального размера. |
| `SelectVariant` | `'inline' \| 'field' \| string` | Визуальный вариант триггера. |

## Модель состояния

- Выбранное значение может быть контролируемым через `value` или неконтролируемым через `defaultValue`.
- Состояние открытия может быть контролируемым через `open` или неконтролируемым через `defaultOpen`.
- Навигацией с клавиатуры, активным вариантом и поиском при наборе управляет корень.
- `value={null}` очищает контролируемое значение, а `undefined` делает select неконтролируемым.
- `typeahead={false}` рекомендуется, когда внутри списка рендерится настоящее текстовое поле.

## Заметки по интеграции

- Используйте `SelectHiddenSelect`, когда значение должно участвовать в нативной отправке формы.
- Список рендерится в top layer, поэтому `overflow`, трансформации и модальные диалоги не обрезают и не перекрывают его.
- Избегайте значений-объектов. Публичный API рассчитан только на значения `string` и `number`.