GrPopover

Роль универсального поповера какое-то время исполнял GrDropdown, но он про меню: жёстко объявляет role="menu", aria-haspopup="menu" и водит фокус по пунктам. Для формы, подтверждения или палитры это неверная семантика — диктор объявит меню там, где меню нет.

Здесь наоборот: role задаётся пропом (dialog по умолчанию, плюс menu, listbox, grid, group и none), потому что клавиатурный паттерн внутри панели принадлежит содержимому. На этом примитиве собираются меню, контекстные меню, палитры и Popconfirm.

Слот #trigger получает triggerProps — их нужно навесить на реальный фокусируемый элемент, а не на обёртку:

<GrPopover>
  <template #trigger="{ triggerProps }">
    <GrButton v-bind="triggerProps">Открыть</GrButton>
  </template>
</GrPopover>

aria-expanded и aria-controls обязаны жить на самом интерактивном элементе: на div вокруг него они немы. Клик при этом слушает обёртка — поэтому триггером может быть что угодно, лишь бы ARIA уехала на кнопку.

trigger="manual" отключает открытие по клику: момент открытия решает потребитель через v-model:open. Это режим контекстного меню и подтверждений.

И это не упущение. Немодальный слой не блокирует страницу, поэтому Tab обязан уводить фокус наружу — иначе пользователь заперт в панели на работающей странице.

modal включает второй режим: фон уходит в inert, Tab ходит по кругу внутри панели, скролл страницы блокируется, а слой встаёт в стек модальным — как окно. Нужен поповеру с формой или подтверждением: без изоляции фона пользователь уводит фокус на ту самую страницу, к которой поповер и относится. В этом режиме фокус переносится в панель независимо от autoFocus — фон недоступен, и слой без фокуса внутри стал бы клавиатурной ловушкой.

Модальность приходит той же сборкой, что у окна, drawer’а и просмотрщика, так что второй реализации модального слоя в пакете нет. Стек, Esc и возврат фокуса на триггер — ../overlays.md.

Панель фокусируемая (tabindex="-1"), и при открытии фокус переносится именно на неё. Сфокусировать первый контрол за пользователя — решение содержимого, а не оболочки: в фильтре это уместно, в подтверждении удаления — нет.

Для role="dialog" имя обязательно: либо ariaLabel, либо labelledBy с id видимого заголовка внутри панели. Панель без имени диктор объявит как «диалог» и ничего больше.

closeOnEsc и closeOnClickOutside включены по умолчанию. closeOnContentClick — нет: он удобен меню, где клик по пункту и означает выбор, и вреден форме, где каждый клик по полю закрывал бы панель.

Императивно — open(), close(), toggle() через ref компонента. Этот набор в пакете считается эталонным для оверлеев и закреплён гейтом overlayImperativeApi.

Панель лежит на той же высоте, что GrDropdown (--gr-z-dropdown), и это осознанно: оба — якорные немодальные оверлеи одного класса, и на разных высотах они начали бы перекрывать друг друга в зависимости от порядка открытия. Шкала слоёв — ../z-index.md.

placement и offsetPx задают сторону и зазор; итоговая сторона может отличаться от заданной — панель переворачивается, когда места не хватает, и transform-origin анимации переворачивается вместе с ней.

size задаёт внутренние отступы и кегль по контрольной шкале — см. ../sizes.md.

triggerProps несут и ARIA, и клик. Биндить их надо на сам интерактивный элемент, а не на обёртку вокруг него:

<GrPopover>
  <template #trigger="{ triggerProps }">
    <GrButton v-bind="triggerProps">
      Открыть
    </GrButton>
  </template>
</GrPopover>

Причина не в аккуратности, а в поведении. Слот #trigger может содержать не только триггер: кнопку рядом, ссылку в карточке, крестик на чипе. Клик, живущий на обёртке, ловил бы их все и открывал панель мимо намерения пользователя. Живущий в triggerProps — открывает только с того элемента, которому его отдали.

Слот, оставленный без v-bind="triggerProps", по-прежнему открывается кликом по обёртке: так работало раньше, и это не отняли. Но такой триггер остаётся без клавиатуры и без aria-haspopup/aria-expanded — панель для скринридера не объявлена, и с Tab до неё не добраться. В dev-сборке компонент предупреждает о таком триггере в консоли.

trigger — click (по умолчанию), manual или hover.

manual открывает только программно, через v-model:open: так работают контекстное меню и подтверждения, где момент открытия решает потребитель.

hover открывает по наведению с задержками openDelay и closeDelay. Нужны обе, и каждая по своей причине: без первой панель выпрыгивает на любое пересечение курсором, без второй её не удержать при переходе с триггера на панель — между ними зазор offsetPx. Наведение слушает и панель, поэтому курсор, переехавший на неё, панель не гасит.

Клик в режиме наведения продолжает работать. С клавиатуры и с тачскрина наведения не бывает, и панель, открываемая только курсором, для них не существует вовсе.

Обёртка вокруг слота #trigger по умолчанию inline-block: она обжимает содержимое, и панель встаёт у края самой кнопки, а не у края колонки. Для кнопки это верно.

Форм-контролу — нет. Контрол объявляет себя w-full, как GrInput и GrSelect, но w-full резолвится относительно обёртки, а она уже обжалась по содержимому. Итог: контрол во всю ширину рисуется по содержимому, а рядом с полем ввода это читается как сбитая вёрстка. Замер: GrColorPicker в GrFormField шириной 384px рисовался на 113px.

Проп block растягивает обёртку на всю ширину родителя:

<GrPopover block>

Имя то же, что у GrButton и GrSegmented, — в ядре это устоявшееся слово для «во всю ширину». matchWidth при этом берёт ширину именно у обёртки, поэтому с block панель пойдёт по ширине поля, а не по ширине содержимого триггера.

Две независимые оси и один предел, который не настраивается.

Потолок содержимого — хук --gr-popover-max-width, по умолчанию 22rem. Это читаемая ширина колонки текста, и для формы или карточки она верна. Содержимому шире прозы — тулбару, палитре, сетке — потолок снимают:

<GrPopover content-class="[--gr-popover-max-width:100vw]">

Хуком, а не пропом, намеренно: значение остаётся значением, его можно менять по брейкпоинту (md:[--gr-popover-max-width:100vw]) и по теме, и оно не спорит по специфичности с классом панели.

100vw, а не none: min(none, …) — невалидный CSS, и запись через 100vw заодно оставляет на месте второй предел.

Через contentClass, а не инлайновым стилем. Панель телепортируется в портал (#gr-portal в body), поэтому обёртка триггера ей не предок: <GrPopover style="--gr-popover-max-width: 100vw"> ляжет на обёртку, до панели не дойдёт и молча ничего не сделает. contentClass — единственный путь на саму панель. Глобально хук работает как обычно: в теме или на :root он наследуется в портал вместе со всем остальным.

Ширина от триггера — проп matchWidth. true — точно ширина триггера, 'min' — не уже его, дальше по содержимому. Панель у поля или у широкой кнопки, оказавшаяся уже своего триггера, читается как ошибка вёрстки.

<GrPopover match-width>            <!-- ровно ширина триггера -->
<GrPopover match-width="min">      <!-- не уже триггера -->

Оси сочетаются, а не спорят, но разрешаются по-разному, и это следствие CSS, а не решение компонента:

Второе — не изъян, а смысл режима: min означает «не уже триггера», то есть пол, а пол по определению главнее потолка. Нужен именно потолок — берите matchWidth без min.

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

Не шире вьюпорта — не настраивается. calc(100vw - 1rem) стоит вторым операндом min() и снаружи не отключается ничем, включая --gr-popover-max-width: 100vw: позиционирование смещает панель в пределах экрана, но не сужает её, и без этого предела панель у края уезжала бы за него.

Устроена как ширина — min() из хука и предела, который не настраивается, — но второй операнд здесь не константа, а замер.

Потолок содержимого — хук --gr-popover-max-height, по умолчанию 100vh, то есть мнения нет. Задают его, когда панель обязана быть ниже доступного места:

<GrPopover content-class="[--gr-popover-max-height:20rem]">

Через contentClass и по той же причине, что у ширины: панель телепортирована, инлайновый стиль ляжет на обёртку и до неё не дойдёт.

Не выше, чем есть места, — не настраивается. Второй операнд — переменная --gr-floating-available-height, которую пишет слой: расстояние до края вьюпорта на той стороне, куда панель встала. Она пересчитывается вместе с позицией, в том числе на скролле, и снаружи не отключается.

Статичной эта величина быть не может, и в этом всё отличие от ширины: 100vw известен заранее, а сколько места под триггером — зависит от того, где триггер стоит. flip перевернёт панель на свободную сторону, shift подвинет вдоль края, но сжать её не может ни тот, ни другой: панель выше вьюпорта после обоих остаётся выше вьюпорта, и её низ уходит за экран без всякой возможности туда добраться.

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

Это касается и всего, что стоит на GrPopover: длинное меню GrDropdown или GrContextMenu у нижнего края экрана теперь сжимается со скроллом, а не съезжает.