GrSidebar

<GrSidebar landmark="navigation" aria-label="Main navigation">
  …
</GrSidebar>

The root is an <aside> (landmark="complementary", the default) or a <nav> (landmark="navigation"). The component does not draw a nested <nav> inside the <aside>: two landmarks for one panel clutter the overview of a screen reader, and a filter panel is not navigation at all — it is the consumer’s side that decides what the panel is.

ariaLabel is mandatory where there is more than one panel on the page: without a name the landmarks in the overview are indistinguishable.

The header is drawn when there is something to show in it: a title or a subtitle — through the title/subtitle prop or through the #title/#subtitle slot — or the showToggleButton button. The slot is stronger than the prop, and a slot alone is enough:

<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="Administration">
  <GrSidebarItem label="Billing" icon="i-lucide-credit-card" />
  <GrSidebarItem label="Settings" icon="i-lucide-settings" />
</GrSidebarGroup>

A group is declared role="group" and is linked to its heading through aria-labelledby. In a collapsed panel there is nowhere for the heading to fit: it is hidden, and the sections begin to be separated by a line — without it the icons of neighbouring groups merge into a single column. The name of the group is not taken out of nothing in the process: aria-labelledby is removed together with the heading.

collapsed supports v-model:collapsed, and the panel works both as controlled and as self-contained. show-toggle-button adds the button; its label comes from the locale (gr.sidebar.expand / gr.sidebar.collapse) and is overridden with the toggleLabel prop.

The chevron always points where the panel will go: on a right-hand panel “collapse” is an arrow pointing right.

When collapsed, a GrSidebarItem shows the icon, and without one the first letter of the label. The item gets its name from aria-label, and the label is shown by a GrTooltip — at the side of the panel, in its direction: to the right for a left-hand one, to the left for a right-hand one.

The tooltip also appears on focus, not only on hover: otherwise there was no way to tab through a collapsed panel and know where you are — a native title does not answer the keyboard at all.

overlay turns the panel into a modal layer: a backdrop, Esc, a focus trap, scroll locking, the return of focus to the element that opened it. All of that is taken from the shared useModalOverlay that GrDrawer and GrPopover live by — the panel has no copy of its own.

<GrSidebar v-model:open="menu" :overlay="isNarrow" aria-label="Sections">
  …
</GrSidebar>

When to switch it on is decided by the application. The package has no breakpoint system of its own, and asking the environment in setup is not allowed: matchMedia gives different answers on the server and in the first client render, and the hydration diverges. The application knows its breakpoints and passes the ready answer as a prop.

The markup of the panel is one for both modes. The wrapper of the layer is always drawn, but outside overlay it is display: contents and disappears from the layout. Had we duplicated the panel for the two modes, the copies would have diverged silently. Hence a consequence: the root of the component is that wrapper, so the consumer’s attributes go to the panel itself by an explicit v-bind rather than by inheritance.

What changes in the layer:

• collapsing is ignored — a rail the width of an icon inside a modal window is half the screen spent on emptiness; the panel keeps its full width and the title;
• the button in the header closes rather than collapses: there is nothing to collapse there, and otherwise closing is possible only with Esc or the backdrop. And it is named accordingly — “Close sidebar” (gr.sidebar.close) rather than “Collapse sidebar”; toggleLabel is stronger;
• before mounting the layer is not drawn at all. The teleport switches on only after mounting (otherwise the first client render would diverge from the server one), and the panel must not flash in the flow of the page in that frame.

Sub-items are put into the item itself — and it becomes an expandable branch:

<GrSidebarItem label="Billing" icon="i-lucide-credit-card" default-expanded>
  <GrSidebarItem label="Invoices" />
  <GrSidebarItem label="Plan" />
</GrSidebarItem>

The depth is counted by the markup, not by a prop. Every item declares to its children a level one greater than its own, so a moved branch does not need renumbering: the levels are recomputed by themselves. The indentation is set on the whole row, not on its text — had we shifted only the label, the active background would have run under the neighbouring level. The step is configured with the --gr-sidebar-nest-indent token.

Expansion lives locally (default-expanded sets the initial state), and v-model:expanded takes it outside.

A branch cannot be a link at the same time. One press is not able both to lead to a page and to expand a subtree, so the sub-items are stronger: an item with them becomes a <button aria-expanded>, and href and as are not used. In the dev build the console warns about that — navigation silently removed is indistinguishable by behaviour from navigation forgotten.

A collapsed subtree is not drawn rather than hidden: an invisible branch would catch Tab and be read by the screen reader contrary to aria-expanded="false".

In the collapsed rail there are no sub-items

They do not fit into sixty-four pixels, and a flyout submenu is a different, far larger story. So the rail shows only the top level, and a press on a branch first gives the panel its width back and expands it: otherwise it would be a button from which nothing happens.

Hence a consequence for the consumer: while the panel is collapsed, an active sub-item does not show itself in any way. If that matters, mark its branch active as well.

The container of the content scrolls and is therefore a Tab stop with a visible focus ring: otherwise a panel with text content cannot be scrolled without a mouse.

An unavailable item (disabled) stops being a button — it renders as a <span>, does not catch the focus and is dimmed with the --gr-disabled-fg token rather than with transparency.