GrAutocomplete

• вариантов слишком много для списка — пользователи, города, теги, репозитории: их ищут вводом, а не просматривают;
• список приходит с сервера — source и debounce вместе с состояниями «идёт поиск» и «ничего не найдено»;
• нужен минимум символов — minQueryLength не даёт уйти на сервер за первой же буквой;
• значений несколько — multiple показывает выбранное чипами, каждый снимается с клавиатуры;
• значения может не быть в справочнике — allowCustomValue разрешает своё.

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

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 подавлен), поэтому выбор мышью оставляет каретку в поле — панель не переоткрывается и таб-порядок не сбивается.

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.

const box = useTemplateRef('box')
box.value?.focus()
box.value?.open()
box.value?.close()

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-результаты не трогает.