# Listbox: API

## Пропсы корня

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `multiple` | `M` | — | Нет | Позволяет выбирать несколько вариантов. Определяет форму `value`: массив, когда true. |
| `value` | `M extends true ? V[] : V \| null` | — | Нет | Текущее выбранное значение (контролируемо). Без `multiple` значение `null` очищает выбор, а `undefined` делает список неконтролируемым. |
| `defaultValue` | `ListboxValue<V, M>` | — | Нет | Значение, выбранное по умолчанию (неконтролируемо). |
| `onChangeValue` | `(value: ListboxValue<V, M>) => void` | — | Нет | Колбэк, вызываемый при изменении выбора. |
| `disabled` | `boolean` | — | Нет | Запрещает взаимодействие и убирает список из порядка обхода по Tab. |
| `size` | `OptionSize` | `'md'` | Нет | Визуальный размер вариантов. |
| `typeahead` | `boolean` | `true` | Нет | Включает переход к варианту при наборе начала его подписи. |
| `ref` | `Ref<HTMLDivElement>` | — | Нет | Ref, передаваемый на элемент списка. |

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

## Дочерние части

### ListboxOption

- `value`: значение, которое передаётся в `onChangeValue` при выборе варианта. Обязательный.
- `label`: простой текст для поиска при вводе, используется вместо текста содержимого.
- `disabled`: делает вариант недоступным.
- `size`: переопределяет размер списка.

### ListboxGroup

Группирует связанные варианты, как нативный `optgroup`. Назовите группу через `aria-labelledby`, указывающий на ваш заголовок, или через `aria-label`.

### `ListboxOption`

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

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

### `ListboxGroup`

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

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

## Типы

- `ListboxProps<V, M>`: `V` — тип значений, `M` равен `true` при `multiple`
- `ListboxOptionProps<V>`
- `ListboxGroupProps`
- `ListboxValue<V, M>`

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

- Список владеет выбором, активным вариантом и поиском при вводе.
- Без `multiple` значение — один вариант, с `multiple` — массив.