GrList

Список рисует под собой GrCard, и variant доходит до неё:

<GrCard>
  <h3>Настройки</h3>
  <GrList variant="ghost">…</GrList>
</GrCard>

ghost убирает рамку и тень — список внутри уже существующей карточки не даёт вторую. Без пропа вариант берётся из GrConfigProvider (componentDefaults.GrCard.variant), иначе — elevated.

Список обрезается по радиусу этой карточки. Своего радиуса у строки нет и не нужно — строки идут вплотную, — но поля у карточки тоже нет, и без клипа фон первой и последней строки заливал бы её углы: постоянно у disabled и по наведению у кликабельной.

Список сам видит, что пунктов нет: v-for по пустому массиву оставляет фрагмент без узлов, v-if — комментарий, и ни то ни другое пунктом не является. Условие v-if/v-else вокруг списка писать больше не нужно.

<GrList>
  <GrListItem v-for="item in items" :key="item.id" :title="item.title" />

  <template #empty>
    Ни одной заявки. <GrButton size="sm">Создать</GrButton>
  </template>
</GrList>

Без слота показывается приглушённая строка emptyText (по умолчанию — ключ gr.list.empty). Проп empty остаётся escape-hatch’ем в обе стороны: там, где слот заполнен, скажем, заголовками групп, потребитель знает про пустоту лучше.

Разделители в пустой ветке не рисуются — иначе висела бы линия ни между чем.

Заглушка не оборачивается в GrEmptyState: список уже внутри карточки, и получилась бы карточка в карточке. Богатое пустое состояние кладётся в слот осознанно.

<GrList :loading="pending" :loading-rows="5" />

Вместо пунктов — строки GrSkeleton той же плотности, контейнер помечен aria-busy="true". Слот #loading заменяет заглушки целиком. Загрузка сильнее пустоты: иначе список мигал бы текстом «пока пусто» на каждом запросе.

<GrListItem title="Профиль" href="/settings/profile" />

<GrListItem title="Выйти" clickable @click="signOut" />

<GrListItem title="Раздел" :as="RouterLink" :to="{ name: 'section' }" />

Порядок выбора тега — as → <a href> → <button clickable> → <div>, как у GrSidebarItem.

Ключевая деталь разметки: role="listitem" остаётся на обёртке, а строка целиком — вложенный элемент. <a role="listitem"> потерял бы роль ссылки, а интерактив снаружи GrListItem разорвал бы связку role="list" → role="listitem" и список перестал бы быть списком.

Структура одна на любой пункт: обёртка держит роль, вложенный элемент — вид и поведение. У обычной строки это <div>, у кликабельной — <a>, <button> или тег из as; отличает их атрибут data-gr-list-item-action, который есть только у кликабельной.

Отсюда же to — проп, а не атрибут: атрибуты компонента достаются обёртке с ролью, и до компонента-ссылки из as цель перехода иначе не доехала бы.

as называет тег, а не поведение. Строка, которой тег нужен ради разметки, остаётся ровно тем же, чем была:

<GrListItem title="Профиль" as="article" />

Меняется только тег: ни подсветки под курсором, ни кольца фокуса, ни атрибута data-gr-list-item-action. Контролом строку делают href, clickable и компонент-ссылка — то есть поведение, которое кто-то действительно обещал.

as="li" тут не подходит, и это не придирка: контейнер списка — div с role="list", а <li> обязан лежать в <ul> или <ol> (axe: listitem). Роль пункта уже несёт обёртка — тег из as нужен содержимому, а не списку.

Действие на теге вне таб-порядка — ошибка вёрстки. <span> с обработчиком клика работает для мыши и только для неё: он не попадает в таб-порядок и не отвечает на Enter (WCAG 2.1.1). Клик такая строка эмитит — молча выключить его значило бы сломать работающий код, — но кольца фокуса не получает и ловит предупреждение в dev-сборке. Компоненты роутера проходят молча: они рендерят <a>, и до рендера этого не узнать.

hoverable подсвечивает строку при наведении, не делая её кнопкой. disabled возвращает строку к неинтерактивному виду, гасит её фоном --gr-muted (не opacity — прозрачность разбавляет выверенные на AA токены) и глушит событие click.

density у пункта: regular (12px) или compact (8px). divided у списка включает разделители между пунктами — по умолчанию включены.

Заголовок и описание строки идут от --gr-text-sm — размер меняется вместе со шкалой темы, а иерархию внутри строки держат вес и цвет.

Классы обеих карт живут в grListStyles.ts и целиком объявлены в safelist.

С пропом items пункты рисует слот #item, а не слот по умолчанию. Прежний режим при этом цел и остаётся дефолтом: items его не заменяет, а добавляет второй способ.

<GrList :items="rows" item-key="id">
  <template #item="{ item }">
    <GrListItem :title="item.title" :description="item.subtitle" />
  </template>
</GrList>

item-key — имя поля или функция (item, index); без него ключом идёт индекс. Пустоту список в этом режиме видит по длине items, а не по содержимому слота.

max-height (число — пиксели) делает контейнер скроллером и добавляет ему tabindex="0": скроллящийся блок обязан быть достижим тем, кто без мыши. Проп работает и сам по себе — включение виртуализации ниже вид не меняет.

virtual оставляет в DOM только окно вокруг вьюпорта. Требует items (иначе размер набора списку неоткуда взять) и max-height (иначе нет вьюпорта); без любого из двух в dev-сборке будет предупреждение.

<GrList :items="builds" item-key="id" virtual :max-height="320">
  <template #item="{ item, aria }">
    <GrListItem v-bind="aria" :title="item.title" />
  </template>
</GrList>

v-bind="aria" обязателен. В DOM живёт неполный набор, и без aria-setsize/aria-posinset диктор посчитает пункты по окну — объявит «3 из 12» на списке в пять тысяч. Поставить атрибуты за потребителя список не может: разметка пункта принадлежит слоту. Поэтому набор приходит готовым объектом, а забытый проброс ловится после монтирования и печатает предупреждение — тишины не будет. Вне виртуального режима aria пуст: полный набор браузер считает сам.

Высота пункта уточняется замером, но до первого рендера её неоткуда взять — оценка задаётся estimated-item-size (по умолчанию 56, строка обычной плотности с описанием). Грубая оценка не ломает прокрутку, но делает бегунок неровным на первых кадрах.

scrollToIndex(index, align?) доступен через ref на списке — единственный способ добраться до пункта вне окна: в DOM его нет, и scrollIntoView не по чему звать.

Общие правила и ограничения приёма — docs/virtual-list.md.