GrDataTable

rowKey (по умолчанию поле id) участвует и в :key для Vue, и в выборе строк. Строка, у которой значения по ключу нет, получает синтетический ключ, привязанный к идентичности объекта, и в dev-режиме компонент один раз предупреждает об этом в консоль.

Синтетический ключ переживает сортировку, но не переживает перезагрузку данных: после нового fetch он у той же строки будет другим, а значит v-model:selected из прошлого набора не совпадёт ни с чем. Для таблиц с выбором задавайте rowKey явно — полем или функцией:

<GrDataTable :rows="rows" :columns="columns" :row-key="row => `${row.type}:${row.id}`" />

Компонент сортирует сам, пока не задан externalSort (тогда rows приходят уже отсортированными, а таблица только сообщает о смене через update:sortKey/update:sortDir/sortChange).

sortable: true над серверной пагинацией — ловушка. Сортируется переданный массив, то есть текущая страница: колонка «максимальное списание» покажет максимум по двадцати видимым строкам, а прочитается как максимум по журналу. Пришли постраничные данные — сортировка уходит в запрос:

<GrDataTable
  v-model:sort-key="sortKey"
  v-model:sort-dir="sortDir"
  :rows="page.data"
  :columns="columns"
  external-sort
  @sortChange="reload"
/>

Выбор здесь не между «сортировка врёт» и «сортировки нет»: externalSort оставляет заголовки кликабельными и объявляет направление в aria-sort, а порядок строк считает тот, кто знает про все страницы.

Правила сравнения живут в grDataTableSort.ts и тестируются без монтирования:

• пустые значения (null, undefined, пробельная строка) — всегда в конце, в обоих направлениях. Приведение к числу через Number() считало бы их нулём, и пустые ячейки оседали бы в середине числового ряда;
• числа, числовые строки, Date и boolean сравниваются численно;
• остальное — localeCompare с sensitivity: 'base' и numeric: true, на локали i18n-адаптера, а не на локали браузера.

sortCycle="asc-desc-none" добавляет третий клик, снимающий сортировку; императивно то же делает clearSort().

Стартовый порядок задают initialSortKey и initialSortDir (asc по умолчанию) — это не то же самое, что sortKey/sortDir: первые задают начальное состояние и дальше не мешают пользователю, вторые делают сортировку управляемой, и тогда её меняет только родитель. Задать нужно одну пару из двух: вместе они означали бы, что таблица получила и начальное значение, и владельца состояния.

Кнопка сортировки называется подписью колонки — её же читает AT при переходе по ячейкам. Направление объявляет aria-sort на <th>, а «что произойдёт по нажатию» — скрытый текст внутри кнопки (sr-only). aria-label на кнопке здесь запрещён: он подменяет собой имя <th>, и вместо «Название» диктор читает «Отсортировано по Название по возрастанию, нажмите…».

Загрузка и пустое состояние объявляются живым регионом, который существует с первого рендера и пуст, пока объявлять нечего: регион, появляющийся сразу с текстом, часть AT не объявляет вовсе.

selectable + v-model:selected (массив ключей). Без v-model:selected таблица держит выбор внутри себя — как и сортировка без sortKey.

selectableRow исключает строку из выбора: у неё не рендерится чекбокс, и она не попадает в «выбрать все». «Выбрать все» работает по видимым строкам и не трогает ключи, которых сейчас нет на экране (например отфильтрованные).

Навигационный клик (@row-click) гасится ровно на чекбоксе: отметить строку и уехать по переходу одним кликом нельзя. Сама служебная ячейка остаётся обычной ячейкой строки — у исключённой из выбора строки, где чекбокса нет, она кликается как любая другая.

• @row-click отдаёт { row, index, event };
• rowClass — строка или функция от строки;
• rowProps — произвольные атрибуты (data-*, title);
• слоты #cell-<key>, #header-<key>, #summary-<key>, #empty, #loading, #caption, #footer;
• emptyText/loadingText — если хватает текста без слота;
• width у колонки — число (пиксели) или строка ('30%', '12rem'); уезжает в заголовочную ячейку и работает в любом режиме.

summaryRow — значения по ключам колонок. Строка встаёт в <tfoot> по той же колоночной сетке, что и тело:

<GrDataTable :rows="rows" :columns="columns" :summary-row="{ channel: 'Итого', net: total }" />

Колонка, которой в объекте нет, остаётся пустой ячейкой — заполнять весь ряд итог не обязан. Ноль при этом печатается: «итог ноль» и «итога нет» — разные утверждения.

Почему проп, а не разметка руками. GrTable намеренно не оформляет ячейки, и собранная в #footer строка получает свои паддинги — а они привязаны к size. Достаточно поставить таблице size="lg", и вручную прописанный px-3 py-2 разъедется с телом на четыре пикселя по обеим осям. То же с выравниванием, шириной и закреплением: align="right", width и pinned пришлось бы воспроизводить на каждой ячейке. summaryRow берёт всё это из тех же функций, что и строка тела.

Оформление ячейки — слот #summary-<key>, скоуп отдаёт value и column:

<GrDataTable :rows="rows" :columns="columns" :summary-row="summaryRow">
  <template #summary-net="{ value }">
    <span class="text-[var(--gr-danger-text)]">{{ money(value) }}</span>
  </template>
</GrDataTable>

Тона у строки нет по умолчанию и нет пропом: «возвраты» и «прибыль» — разные сообщения, и выбрать за приложение компонент не может. По умолчанию итог получает только отбивку и вес.

Итог не суммируется компонентом: что считать итогом — фильтры, страница, весь журнал — знает приложение, а не таблица.

#footer остаётся: он для того, что в одну типизированную строку не ложится — несколько итогов, примечание, colspan. Рендерится в тот же <tfoot> после строки summaryRow, поэтому содержимое слота — тоже строки таблицы (<tr><td>), а не свободный блок. flex justify-between там даст блок, который лежит под таблицей, но не стоит под своей колонкой.

Скоуп отдаёт колонки в текущем порядке и их полное число вместе с колонкой выбора — чтобы colspan не подбирался на глаз:

<GrDataTable :rows="rows" :columns="columns">
  <template #footer="{ totalColumns }">
    <tr>
      <td :colspan="totalColumns">
        Возвраты учтены в строке «Итого»
      </td>
    </tr>
  </template>
</GrDataTable>

columns нужен, когда строка считается по нескольким колонкам: порядок там пользовательский (columnOrder), и повторять его руками — значит разойтись с шапкой при первом же переносе колонки.

virtual вместе с maxHeight оставляет в DOM только окно вокруг вьюпорта.

<GrDataTable :rows="rows" :columns="columns" virtual sticky-header :max-height="420" />

Распорки здесь — строки, а не псевдоэлементы. У списочных компонентов срезанное держат ::before/::after контейнера, но в таблице так нельзя: <tbody> игнорирует padding, а псевдоэлемент внутри группы строк не образует строку с управляемой высотой. Поэтому сверху и снизу встают служебные <tr> с одной ячейкой на все колонки — той же формы, что строки загрузки и пустоты, — и они скрыты от скринридера.

Меряется группа строки, а не строка. Тело собрано группами по строке в каждой, и замер висит на группе — иначе второй ярус раскрытой строки в высоту не попадал бы (см. «Второй ярус строки»).

Раскладка фиксируется. Ширина колонки считается по содержимому всех строк, а в DOM их только окно: без фиксации колонки прыгали бы на каждой прокрутке. Задайте width у колонок — иначе фиксированная раскладка делит место поровну, и узкий # получит столько же, сколько Email.

Число строк объявляется явно. Диктор считает строки по разметке, а там окно, поэтому таблица отдаёт aria-rowcount, а строки — aria-rowindex (заголовок первый, набор начинается со второго). В обычном режиме этих атрибутов нет: там набор виден по DOM. Устройство примитива — virtual-list.md.

reorderable-columns добавляет в каждую ячейку шапки ручку переноса. Колонка тянется указателем (мышью и пальцем) и двигается с клавиатуры — Shift+←/→ на ручке; результат объявляется в живой регион.

<GrDataTable
  v-model:column-order="order"
  reorderable-columns
  :columns="columns"
  :rows="rows"
/>

v-model:column-order — массив ключей. Без него порядок таблица помнит сама, как и сортировку без v-model:sortKey. Рядом идёт событие columnReorder ({ key, from, to }) — им удобно сохранять одну операцию, а не весь список.

Состав колонок задаёт columns, порядок — только порядок. Ключ, которого в наборе нет, игнорируется; колонка, которой нет в порядке (её только что добавили), встаёт в конец. Иначе правка columns теряла бы колонки молча.

Ручка — своя кнопка, а не сам заголовок: клик по заголовку остаётся сортировкой, и перетаскивание её не перехватывает. В таб-порядке ручки держат одну остановку на всю шапку (roving tabindex), голые ←/→ водят фокус между ними.

resizable-columns добавляет к правому краю каждого заголовка ручку. Ширина тянется указателем, а с клавиатуры ручка ведёт себя как разделитель окна (role="separator", паттерн GrSplitter): ←/→ — шаг 16px, с Shift — 48px, Enter возвращает колонку к авторазметке. То же делает двойной клик.

v-model:column-widths — ширины в пикселях по ключу колонки; без него таблица помнит их сама. Событие columnResize ({ key, width }) приходит на конце жеста и на каждом шаге клавиатуры; ширина 0 означает возврат к авторазметке. Уже 48px колонка не становится — в неё перестаёт помещаться даже стрелка сортировки.

Ширину ручка называет с первого рендера, до всякой протяжки: пока своей ширины у колонки нет, в aria-valuenow идёт измеренная по шапке, а до замера — объявленная в columns.

Режим включает фиксированную раскладку таблицы. Иначе браузер пересчитывает колонки по содержимому и заданная пользователем ширина пропадает на первом же обновлении данных. Оборванный жест (Esc, потеря указателя) возвращает ширину, которая была до нажатия.

pinned: 'left' | 'right' у колонки прижимает её к краю при горизонтальной прокрутке. Смещения внутри группы считаются по измеренным ширинам соседей, поэтому колонке не обязательно иметь width; пересчёт идёт на смене данных и по ResizeObserver.

Три правила, которые стоит знать до того, как это удивит:

• закреплённые колонки всегда стоят группой у своего края — порядок внутри группы пользовательский, но перенести колонку из группы в группу нельзя, иначе «закреплена слева» перестало бы означать «слева»;
• колонка выбора закрепляется вместе с левой группой — иначе чекбокс уезжал бы из-под строки, которая осталась на месте;
• у закреплённой ячейки непрозрачный фон (иначе сквозь неё просвечивает то, что уезжает под низ), поэтому подсветку выбранной строки она повторяет сама.

Закрепление задаёт пользователь

pinnable-columns добавляет в заголовок каждой колонки меню «закрепить слева / справа / открепить», а v-model:pinned-columns хранит выбор по ключу колонки. Без пропа pinned остаётся тем, чем был, — объявлением в конфиге, которое меняется только кодом.

Пункты меню — menuitemradio с checked, а не три команды: закрепление это выбор одного из трёх положений, и в такой форме диктор называет текущее сам. Меню стоит на GrDropdownMenu, поэтому клавиатура, стек слоёв и возврат фокуса приезжают готовыми.

null в модели означает «откреплена», а не «как в конфиге»: без этого различия снять закрепление, объявленное у колонки, было бы нечем — отсутствие ключа как раз и значит «решает конфиг».

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

cell-navigation включает паттерн grid из WAI-ARIA: таблица получает role="grid", занимает одну остановку Tab, и внутрь ведут стрелки.

Шапка — такая же строка сетки: из неё вниз попадаешь в первую строку данных. Кольцо не замкнуто: строка ниже последней — это не первая, а «дальше некуда».

Проп отдельный, а не поведение по умолчанию. Сетка забирает Tab себе, и у всех, кто таблицу уже поставил, таб-порядок бы переставился.

Контролы внутри ячеек из обхода выходят — сортировка, ручки переноса и ширины, меню колонки, чекбокс, кнопка раскрытия. Иначе остановок было бы столько же, сколько контролов, то есть паттерн не выполнялся бы вовсе: до них добираются стрелкой до ячейки и Enter. Ради этого у GrCheckbox есть проп tabindex — свою остановку он держит литералом, и снаружи её иначе не снять.

С виртуализацией работает. Набор ячеек — отрисованное окно, а не вся таблица: у десяти тысяч строк на шесть колонок ключей было бы шестьдесят тысяч. Шаг за край окна прокручивает список и доводит фокус до появившейся строки.

expandable добавляет служебную колонку с кнопкой; под строкой раскрывается слот #detail.

<GrDataTable :rows="rows" :columns="columns" expandable v-model:expanded-keys="open">
  <template #detail="{ row }">
    <OrderLines :order-id="row.id" />
  </template>
</GrDataTable>

Раскрывает кнопка, а не клик по строке: клик по строке уже занят rowClick и выбором, и раскрытие на нём отняло бы у потребителя навигацию. Кнопка гасит всплытие, поэтому раскрытие не выделяет строку.

Колонка стоит перед колонкой выбора: раскрытие относится ко всей строке, а выбор — к её данным.

Состояние хранится по ключу строки, а не по индексу: сортировка раскрытую строку не путает. accordion оставляет раскрытой одну.

Своя кнопка вместо служебной колонки

expand-column="false" убирает столбец с кнопкой; раскрытием тогда управляет разметка потребителя. Слоты ячеек получают expanded и toggleExpand, поэтому кнопка ставится в свой столбец действий рядом с остальными:

<GrDataTable :rows="rows" :columns="columns" expandable :expand-column="false">
  <template #cell-actions="{ expanded, toggleExpand }">
    <GrButton size="xs" :aria-expanded="expanded" @click="toggleExpand">
      {{ expanded ? 'Свернуть' : 'Подробнее' }}
    </GrButton>
  </template>
</GrDataTable>

aria-expanded в этом режиме ложится на вашу кнопку: своей у компонента нет, и повесить состояние ему не на что. Связь с id строки подробностей через aria-controls тоже остаётся за вами.

Подгрузка

loadDetail включает загрузку в момент раскрытия:

<GrDataTable :load-detail="(row, signal) => api.order(row.id, { signal })" expandable>
  <template #detail="{ data }">{{ data.total }}</template>
</GrDataTable>

Второй аргумент — AbortSignal, и прокинуть его в запрос обязательно: строку сворачивают чаще, чем дожидаются ответа, и свёрнутая строка свой запрос отменяет. Ответ, стартовавший раньше и пришедший позже, проигрывает последнему.

Состояния приходят в слот: state — idle | loading | ready | error, data — результат. У загрузки и отказа есть дефолтная разметка (скелет и кнопка повтора), она переопределяется слотами #detail-loading и #detail-error.

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

Загруженное держится, пока строка жива: свернуть и раскрыть снова — запроса нет. Смена идентичности массива rows кэш сбрасывает (мутация на месте — сохраняет), а точечно его сбрасывает invalidateDetail(key?) из императивного API.

Вместе с virtual

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

Обернуть две <tr> в таблице больше не во что: группа строк — единственный контейнер, который для них существует. Поэтому тело таблицы здесь собрано группами по одной строке в каждой (rowGroups у GrTable), а не одной <tbody> на всё. Несколько групп в таблице валидны и для скринридера ничего не меняют: номер строки приходит из aria-rowindex, а не из позиции в разметке.

Побочная выгода: ResizeObserver виртуализатора следит за той же группой, так что раскрытие и подгрузка подробностей уточняют высоту сами — сообщать о них отдельно не нужно.

Доступность

Кнопка несёт aria-expanded и aria-controls на строку подробностей; раскрытие и окончание загрузки объявляются в живой регион. Строка подробностей — не строка набора: aria-rowindex она не получает, и aria-rowcount считается по rows.

Нет группировки строк и редактирования ячеек — это другой класс таблицы.