GrAutocomplete

<GrAutocomplete
  v-model="city"
  :options="[
    { label: 'Европа', options: [{ value: 'lis', label: 'Лиссабон' }] },
    { label: 'Азия', options: [{ value: 'tyo', label: 'Токио' }] },
    { value: 'remote', label: 'Удалённо' },
  ]"
/>

Форма данных та же, что у GrSelect: два соседних контрола, у которых списки различаются только способом ввода, обязаны принимать данные одинаково. Группы и одиночные опции смешиваются в одном массиве.

Фильтр прячет группу целиком, если в ней ничего не совпало. Заголовок над пустотой читается как сбой, а не как «здесь ничего нет».

Клавиатура ходит только по опциям. Заголовок группы стрелками не выбирается и в набор для диктора не входит: прямыми потомками role="listbox" обязаны быть опции, поэтому заголовок лежит внутри своей группы и даёт ей имя через aria-labelledby. При виртуализации окно может начаться ниже заголовка — тогда имя группы уходит в aria-label, и группа всё равно остаётся названной.

Одинаковое значение в разных группах — не ошибка: ключ строки собирается с индексом группы, поэтому две такие опции не схлопываются в один узел, а наведение мышью подсвечивает ту, на которую навели.

Группы приходят и от сервера: fetchOptions вправе вернуть тот же массив с группами, и подпись состава считается по их содержимому — смена опции внутри группы не проходит незамеченной.

Два пути, взаимоисключающих по смыслу.

fetchOptions — запрос ведёт компонент:

<GrAutocomplete
  v-model="user"
  :fetch-options="fetchPeople"
  :min-query-length="1"
  @search-error="reportError"
/>

async function fetchPeople(query: string, signal: AbortSignal) {
  const response = await fetch(`/api/people?q=${query}`, { signal })
  return response.json()
}

Дебаунс, отмена предыдущего запроса и loading — на компоненте. Ответ на отменённый запрос игнорируется: при быстром вводе в списке всегда результат последнего запроса, а не того, который вернулся позже. Локальная фильтрация в этом режиме выключена — список фильтрует сервер. Ошибка (кроме отмены) уходит событием searchError, список при этом становится пустым.

search — запрос ведёт приложение:

<GrAutocomplete
  v-model="user"
  :options="options"
  :loading="pending"
  :filterable="false"
  @search="load"
/>

Путь для тех, у кого запрос живёт в сторе, кэше или своей отмене. Гонку ответов в этом случае разруливает приложение: компонент отдаёт только дебаунснутый запрос и не знает, какой ответ ему принесли.

allowCustomValue добавляет в список опцию «Add …». Она такая же опция списка, как остальные, и участвует в навигации стрелками: без этого закоммитить своё значение с клавиатуры было нельзя — при непустом списке Enter всегда уходил в активную опцию.

Значение набирается текстом, поэтому оно строковое по природе: при числовом TValue ветка неприменима.

Крестики чипов намеренно не табируемы: у combobox фокус живёт на <input>, и двадцать выбранных значений не должны давать двадцать остановок Tab. Навигация — стрелками: ← из пустого запроса переводит на последний чип, ←/→ ходят между ними, Delete/Backspace удаляет, Esc, → с последнего и любой печатный символ возвращают в поле.

Backspace в пустом поле по-прежнему сносит последний чип без захода в навигацию.

Прямые потомки role="listbox" — только опции: роль объявляет остальных недопустимыми детьми. Загрузка, «введите ещё N символов» и «ничего не найдено» живут ниже списка в одном живом регионе role="status" aria-live="polite" — иначе асинхронные состояния менялись бы молча.

Опции не забирают фокус (mousedown подавлен), поэтому выбор мышью оставляет каретку в поле — панель не переоткрывается и таб-порядок не сбивается.

dropdownMaxHeight — потолок списка, а не панели. Саму панель ограничивает место, оставшееся до края вьюпорта: слой сообщает замер в --gr-floating-available-height, и на коротком экране сжимается именно список — поле ввода и строка статуса остаются на виду, а полоса прокрутки одна. Механизм общий на списочные панели пакета и описан в ../overlays.md.

virtual оставляет в DOM только окно вокруг вьюпорта — его высоту задаёт dropdownMaxHeight или доступное место, если его меньше. Профильный сценарий один: удалённый поиск по справочнику, где совпадений тысячи.

<GrAutocomplete v-model="city" :options="cities" virtual />

Три следствия, о которых стоит знать заранее.

Размер набора объявляется явно. В обычном режиме диктор выводит его из DOM, но при неполном наборе получил бы «1 из 12» на списке в десять тысяч. Поэтому при virtual опции несут aria-setsize и aria-posinset — от всего отфильтрованного списка, а не от окна. В обычном режиме этих атрибутов нет: там они были бы шумом.

Строка «Add …» — элемент набора. При allowCustomValue она стоит первой и прокручивается вместе со списком, а не прилипает к верху панели: клавиатура и так ходит по ней как по обычной опции.

Активная опция всегда смонтирована. Стрелки прокручивают список до неё прежде, чем перевести aria-activedescendant, — иначе атрибут указывал бы на узел, которого в DOM нет. Устройство и ограничения примитива — virtual-list.md.

disabled и readonly приходят и пропом, и из GrFormField. Оба запирают контрол одинаково: панель не открывается, опции не выбираются, чипы не удаляются, кнопки очистки нет. Разница только в семантике — readonly отдаёт значение в форму и объявляется aria-readonly.

Слоты кладут в оболочку иконку, единицу или метку; ширина ограничивается шестью пропами (prefixMinWidth/prefixMaxWidth/prefixFixed и то же для суффикса). Общий контракт контролов — form-controls.md.

Панель управляема через v-model:open (общий контракт панельных оверлеев, как у GrPopover): без пропа open — прежнее uncontrolled-поведение, с ним состоянием владеет родитель, а update:open сопровождает каждое изменение.

Проп name включает участие в нативной форме: hidden-инпуты сериализуют значение модели, а не текст запроса — по одному на значение при multiple, ничего при пустом выборе.

Пока запрос короче minQueryLength, панель показывает подсказку «введите ещё N символов», а не результаты прошлого запроса — устаревший список под подсказкой дезинформировал бы. При allowCustomValue подсказка стоит рядом со строкой «Add …»: та объясняет, что делать с набранным, но не то, куда делись опции.

В remote-режиме (fetchOptions) проп options — стартовый список до первого ответа сервера. Его замена родителем снова делает его источником до следующего ответа и отменяет летящий запрос: тот относится к прежнему набору данных. Смена отслеживается по составу, а не по идентичности массива, поэтому инлайн-литерал :options="[...]" безопасен — пересозданный при ререндере список с теми же опциями remote-результаты не трогает.