GrSidebar

<GrSidebar landmark="navigation" aria-label="Основная навигация">
  …
</GrSidebar>

Корень — <aside> (landmark="complementary", по умолчанию) или <nav> (landmark="navigation"). Вложенного <nav> внутрь <aside> компонент не рисует: два лендмарка на одну панель засоряют обзор диктора, а панель фильтров навигацией не является вовсе — сторона потребителя решает, чем панель является.

ariaLabel обязателен там, где панелей на странице больше одной: без имени лендмарки в обзоре неразличимы.

Шапка рисуется, когда в ней есть что показать: заголовок или подзаголовок — пропом title/subtitle или слотом #title/#subtitle, — либо кнопка showToggleButton. Слот сильнее пропа, и одного слота достаточно:

<template>
  <GrSidebar position="right" aria-label="Report filters">
    <template #title>
      Filters <GrBadge>2</GrBadge>
    </template>
    <template #subtitle>
      Applied to every chart
    </template>
  </GrSidebar>
</template>

<GrSidebarGroup label="Администрирование">
  <GrSidebarItem label="Оплата" icon="i-lucide-credit-card" />
  <GrSidebarItem label="Настройки" icon="i-lucide-settings" />
</GrSidebarGroup>

Группа объявлена role="group" и связана со своим заголовком через aria-labelledby. В свёрнутой панели заголовку негде поместиться: он скрывается, а секции начинает разделять линия — без неё иконки соседних групп сливаются в один столбец. Имя группы при этом не берётся из пустоты: aria-labelledby снимается вместе с заголовком.

collapsed поддерживает v-model:collapsed, панель работает и как управляемая, и как самостоятельная. show-toggle-button добавляет кнопку; её подпись приходит из локали (gr.sidebar.expand / gr.sidebar.collapse) и переопределяется пропом toggleLabel.

Шеврон всегда указывает туда, куда уедет панель: у правой панели «свернуть» — это стрелка вправо.

В свёрнутом виде GrSidebarItem показывает иконку, а без неё — первую букву метки. Имя пункту даёт aria-label, а подпись показывает GrTooltip — сбоку от панели, в её сторону: у левой вправо, у правой влево.

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

overlay превращает панель в модальный слой: подложка, Esc, ловушка фокуса, блокировка прокрутки, возврат фокуса на открывший элемент. Всё это берётся из общего useModalOverlay, которым живут GrDrawer и GrPopover, — своей копии у панели нет.

<GrSidebar v-model:open="menu" :overlay="isNarrow" aria-label="Разделы">
  …
</GrSidebar>

Когда включать — решает приложение. Своей системы брейкпоинтов у пакета нет, а спрашивать среду в setup нельзя: matchMedia даёт на сервере и на первом клиентском рендере разные ответы, и гидрация расходится. Приложение знает свои точки перелома и передаёт готовый ответ пропом.

Разметка панели одна на оба режима. Обёртка слоя рисуется всегда, но вне overlay она display: contents и из раскладки исчезает. Продублируй мы панель на два режима, копии разошлись бы молча. Отсюда следствие: корень компонента — эта обёртка, поэтому атрибуты потребителя уходят на саму панель явным v-bind, а не наследованием.

Что меняется в слое:

• свёрнутость игнорируется — рейл шириной в иконку внутри модального окна это половина экрана, потраченная на пустоту; панель держит полную width и заголовок;
• кнопка в шапке закрывает, а не сворачивает: сворачивать там нечего, а закрыть иначе можно только Esc или подложкой. И называется она так же — «Close sidebar» (gr.sidebar.close), а не «Collapse sidebar»; toggleLabel сильнее;
• до монтирования слой не рисуется вовсе. Телепорт включается только после монтирования (иначе первый клиентский рендер разойдётся с серверным), и панель в этом кадре не должна мелькать в потоке страницы.

Подпункты кладутся в сам пункт — и он становится раскрывающейся веткой:

<GrSidebarItem label="Оплата" icon="i-lucide-credit-card" default-expanded>
  <GrSidebarItem label="Счета" />
  <GrSidebarItem label="Тариф" />
</GrSidebarItem>

Глубина считается разметкой, а не пропом. Каждый пункт объявляет своим детям уровень на единицу больше своего, поэтому переставленную ветку не нужно перенумеровывать: уровни пересчитаются сами. Отступ задаётся строке целиком, а не её тексту, — сдвинь мы только подпись, активный фон уезжал бы под соседний уровень. Шаг настраивается токеном --gr-sidebar-nest-indent.

Раскрытие живёт локально (default-expanded задаёт начальное), а v-model:expanded забирает его наружу.

Ветка не может быть одновременно ссылкой. Одно нажатие не в состоянии и увести на страницу, и раскрыть поддерево, поэтому подпункты сильнее: пункт с ними становится <button aria-expanded>, а href и as не используются. В dev-сборке об этом предупреждает консоль — тихо снятая навигация по поведению неотличима от забытой.

Свёрнутое поддерево не рисуется, а не прячется: невидимая ветка ловила бы Tab и читалась бы диктором вопреки aria-expanded="false".

В свёрнутом рейле подпунктов нет

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

Отсюда следствие для потребителя: пока панель свёрнута, активный подпункт ничем себя не показывает. Если это важно, помечайте active и его ветку.

Контейнер контента прокручивается и потому является остановкой Tab с видимым фокус-кольцом: иначе панель с текстовым содержимым не проскроллить без мыши.

Недоступный пункт (disabled) перестаёт быть кнопкой — он рендерится <span>, не ловит фокус и гасится токеном --gr-disabled-fg, а не прозрачностью.