laif-ds 1.0.0 → 1.0.2

package/dist/agent-docs/components/AppSidebar.md

@@ -19,14 +19,18 @@ High-level app sidebar built on top of `Sidebar` primitives. Renders navigation
 | `footerContent`     | `React.ReactNode`                 | `undefined`   | Custom content at the bottom.              |
 | `showRail`          | `boolean`                         | `true`        | Show the draggable sidebar rail.           |
 | `collapsible`       | `"offcanvas" \| "icon" \| "none"` | `"offcanvas"` | Collapse behavior, forwarded to `Sidebar`. |
+| `expandOnHover`     | `boolean`                         | `false`       | Expand as an overlay on hover/focus, with a Pin to make it permanent. Requires `collapsible="icon"`. |
+| `pinned`            | `boolean`                         | `undefined`   | Controlled pin. Alias of the primitive's `open`, not a second state. |
+| `defaultPinned`     | `boolean`                         | `undefined`   | Uncontrolled initial pin, applied once at mount. |
+| `onPinnedChange`    | `(pinned: boolean) => void`       | `undefined`   | Fired on every pin change, from any affordance. Never by a peek. |
 | `linkComponent`     | `React.ComponentType<any>`        | `undefined`   | Custom link component for items.           |
 | `linkProps`         | `Record<string, any>`             | `{}`          | Extra props passed to the link component.  |
 
-`NavGroup` → `{ title: string; url?: string; items: NavItem[]; iconName?: IconName; icon?: NavIcon }`
+`NavGroup` → `{ title: string; url?: string; items: NavItem[]; iconName?: IconName; icon?: NavIcon; badge?: number | string | true; badgeLabel?: string }`
 
-`NavItem` → `{ title: string; url: string; isActive?: boolean; iconName?: IconName; icon?: NavIcon; subItems?: NavSubItem[] }`
+`NavItem` → `{ title: string; url: string; isActive?: boolean; iconName?: IconName; icon?: NavIcon; subItems?: NavSubItem[]; badge?: number | string | true; badgeLabel?: string }`
 
-`NavSubItem` → `{ title: string; url: string; isActive?: boolean; iconName?: IconName; icon?: NavIcon }`
+`NavSubItem` → `{ title: string; url: string; isActive?: boolean; iconName?: IconName; icon?: NavIcon; badge?: number | string | true; badgeLabel?: string }`
 
 `NavIcon` → `React.ComponentType<{ className?: string }>`
 
@@ -47,8 +51,9 @@ Every row takes its icon from one of two channels:
 
 `icon` **takes precedence** when both are set on the same row.
 
-The size is imposed by the sidebar, not by the consumer: it passes a size
-_class_ (`size-5` in a row, `size-4` in a collapsed dropdown or a tab), which is
+The size is imposed by the sidebar, not by the consumer: the row asks for
+`size="sm"` and the **host** decides — **20px** in the 3rem icon rail, **16px**
+everywhere else (expanded row, sub-item, icon-mode dropdown, tab bar) — which is
 why the contract is `className` and not a `size` prop. A CSS width/height
 overrides the `width`/`height` attributes libraries like `react-icons` put on
 their `<svg>`, so the same component lands at the right size in every context.
@@ -82,6 +87,13 @@ Inherits other props from `Sidebar` via `React.ComponentProps<typeof Sidebar>`.
 ## Behavior
 
 - **Collapsible groups**: Clicking items with `subItems` toggles nested lists.
+  The submenu animates open and shut on a `grid-template-rows: 0fr -> 1fr`
+  transition (house duration and curve), which resolves to exactly the
+  sub-items' height without a JS measurement, and the chevron rotates 90deg in
+  step rather than swapping glyph. The rows stay mounted and are hidden with
+  `visibility`, so they leave the tab order and the accessibility tree when
+  shut while `aria-controls` on the toggle keeps pointing at a real element.
+  `prefers-reduced-motion` drops the transition and the toggle is instant.
 - **Active state**: `isActive` highlights the item. An item whose own `isActive`
   or one of whose `subItems` is active starts already expanded at mount, in
   `navigation` and `navigationFooter` alike. Auto-expansion applies once per
@@ -99,6 +111,176 @@ Inherits other props from `Sidebar` via `React.ComponentProps<typeof Sidebar>`.
 - **Rail**: `showRail` displays a thin draggable handle to collapse/expand.
 - **No interactive nesting**: the menu button _is_ the link (`asChild`), so there
   is no `<a>` inside a `<button>`.
+- **Hover expansion**: `expandOnHover` adds a third collapse mode on top of
+  `collapsible="icon"` — see the dedicated section.
+- **Badges**: `badge` marks a row with a count, a short text or a dot, and
+  degrades per surface instead of disappearing — see the dedicated section.
+
+---
+
+## Badges (`badge` / `badgeLabel`)
+
+An optional quantitative mark on a navigation row: unread documents, open
+tickets, a `BETA` section. Two scalar fields, on `NavItem`, `NavSubItem`,
+`NavGroup` and `AppBottomNav`'s `BottomNavItem` alike:
+
+```ts
+badge?: number | string | true;
+badgeLabel?: string;
+```
+
+### The three forms
+
+| Value    | Renders                    | Notes                                                                                                                                                                               |
+| -------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `number` | a count, `99+` past 99     | Integer >= 1. `0` renders **nothing** — a count of zero is the absence of the thing counted; pass `"0"` to really mean the character. Negative or non-integer warns and is ignored. |
+| `string` | short text (`NEW`, `BETA`) | Keep it to 8 characters; over that it warns and is clipped at the pill's `max-w-16`.                                                                                                |
+| `true`   | a dot                      | For state with no number to it. The sentinel is `true` and **not** the string `"dot"`, which is itself a legal short text.                                                          |
+
+`badgeLabel` is the spoken form (`"3 unread documents"`). It is effectively
+required for `badge: true`, which has no text of its own: without it the dot
+stays `aria-hidden` and the component warns — the design system does not invent
+copy for an app it cannot read.
+
+### Degradation per surface
+
+A `NavItem` feeds **four** rendering surfaces, so the badge is a declared
+degradation rather than one component used four times. **Nothing is ever
+dropped silently: at the minimum a badged row shows a dot.**
+
+| Capacity  | Surfaces                                                                                                                                                                                 | Behaviour                            |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `full`    | expanded desktop row, inline sub-item, mobile panel row (both levels), group label (list mode and mobile heading), selected tab, icon-mode sub-item dropdown, group-selector radio items | count · text · dot                   |
+| `compact` | bottom nav cell                                                                                                                                                                          | numbers (`99+` included); text → dot |
+| `dot`     | 3rem icon rail, collapsed group selector, **un**selected tab, Menu cell                                                                                                                  | everything → dot                     |
+
+In the rail the value is not lost, it moves: the tooltip becomes
+`title · value` (`Utenti · 5`) — punctuation, not copy, because the tooltip is
+the only channel at 3rem that can carry a number. The collapsed form is keyed on
+the **peek-aware** state, so during an `expandOnHover` peek the row shows the
+expanded pill, not the dot.
+
+### Counts never aggregate
+
+A parent shows **its own** badge; failing that, and **only while its children
+are not visible**, a dot saying there is something in there. Nothing while the
+submenu is open — the children are right there with their own badges. One row,
+one marker.
+
+The aggregations that exist are all dots, and each covers a surface where the
+state would otherwise be invisible rather than merely smaller:
+
+- **Unselected tab** — the group's own badge, else a dot if any item in that
+  group is badged. The strongest case: the items of an unselected tab are not
+  rendered at all.
+- **Collapsed group selector** — a dot for badged state in a group **other**
+  than the selected one; the selected group's items are listed right below with
+  their own dots, and aggregating them here would mark the same thing twice.
+- **Menu cell** of `AppBottomNav` — `menuBadge` OR the items dropped past the
+  cell budget.
+- **Collapsed parent row**, on every surface, including a mobile level-0 row
+  (whose children live behind the drill).
+
+A sum would be unverifiable arithmetic — overlapping sets,
+permission-filtered children — presented as fact.
+
+### Colour and geometry
+
+One family for every form and every surface: `bg-d-primary` +
+`text-d-primary-foreground`, **measured 7.99:1 in both the light and the dark
+theme**, so it clears 4.5:1 even at the 10px rung the bottom-nav overlay uses.
+(In `claymorphism` the same pair measures 5.75:1; in `tangerine` 3.62:1, which
+is a property of that theme's primary pair — `Button variant="default"` and
+`Badge variant="default"` are the same two tokens — and not something the badge
+introduces.)
+
+- **Inline pill** (`full`): `h-5 min-w-5`, `rounded-md`, `text-xs tabular-nums`,
+  `shrink-0 max-w-16` with an inner `truncate`, so it can never break a row.
+- **Overlay** (`compact`): 14px on the 20px glyph, `rounded-full`,
+  `text-[10px]`, `ring-2 ring-d-card`. Not 16px — that is 80% of the glyph,
+  where 14px is iOS's ratio.
+- **Dot** (`dot`): 10px — 8px of fill inside a 1px `border-d-primary-foreground`.
+  The border is a requirement, not decoration: the fill measures 1.89:1 against
+  the sidebar in the light theme and a **non-text** indicator owes 3:1
+  (WCAG 1.4.11), while the ink measures 15.12:1 there — so the indicator's
+  boundary is what conforms. In the dark theme it is the other way round (fill
+  8.93:1), which is why both are always drawn.
+
+The class strings are private to `nav-badge.tsx` (`pillClassName` /
+`dotClassName` / `overlayClassName`). They
+introduce **no new `--d-*` variable**, so there is nothing to mirror into the
+Tailwind v3 entry.
+
+### Accessibility
+
+- `aria-hidden="true"` on the visual badge, plus an in-flow `sr-only` span with
+  `badgeLabel` **inside the row element**. The name composes as
+  "Documenti, oltre 99 documenti non letti, current page" and never
+  "Documenti 99+".
+- **Not** an `aria-label` on the row: it would override the visible label (WCAG
+  2.5.3), fight an `aria-label` a consumer puts on its own `LinkComponent`, and
+  destroy the text node the truncated label rests on.
+- **Not** `aria-describedby`: descriptions are announced late or suppressed in
+  browse mode by several AT, and a count is the row's identity, not its
+  description.
+- `aria-current` is **untouched** on every surface.
+- Aggregate dots are visual only. They have no text of their own, and what they
+  stand for is announced on the row that owns it, one level in.
+
+### Live counts vs static ones, and who announces them
+
+The design system assumes **neither**, and it never renders a live region. A
+count may be a static fact of the route table or a number that ticks in the
+background; the badge renders whatever it is given, and:
+
+1. The navigation is not where the user's attention is. Announcing "3"
+   interrupts a task they chose, for information they did not ask for.
+2. WCAG 4.1.3 covers status messages that follow a **user action**. A
+   background polling tick is not one.
+3. The value is already in the item's accessible name, one landmark jump away.
+4. With several badged items and any polling, a `role="status"` becomes a
+   stream.
+
+**The exception, and it belongs to the app**: when a count changes as the direct
+result of an action on the current screen, the _app_ announces it in its own
+status region next to that action — not the navigation. `AppBottomNav`'s badge
+follows the same contract.
+
+### What this deliberately does not do
+
+The answers to the requests that come back, so they are on the record:
+
+1. **No per-item colour or `variant`** (`destructive`, `success`, `warning`).
+   Colour in a navigation is already the vocabulary of "you are here", and
+   per-item severity turns navigation into a dashboard. The measurement decides
+   it too: the red badge that gets asked for is `bg-d-destructive` +
+   `text-d-destructive-foreground` at **3.30:1**, failing 4.5:1 on day one.
+2. **No `ReactNode` or render-function badge.** The node escape hatch is
+   deliberately `AppBottomNav`'s Menu cell alone; a node badge puts avatars and
+   spinners in nav rows and breaks both the ~8-character label budget and the
+   rail's geometry.
+3. **No reuse of `<Badge>`** from `badge.tsx` in nav rows, and none of its 16
+   variants exposed there: it is `shrink-0 whitespace-nowrap w-fit` with no
+   `truncate`, so it does not give way.
+4. **No aggregated counts** anywhere — parent, tab, group selector, Menu cell.
+   Hidden state surfaces as a dot.
+5. **No counts past 99**, no `1.2k`, no `1,203`. The overflow is `99+`; four
+   characters do not fit the compact surfaces.
+6. **No motion at all**: no pulse, no ping, no animated counter, no enter/exit
+   transition. The only place a badge moves is inside the selected tab's
+   existing clip-and-fade, which it inherits by living in the label's grid.
+7. **No interactive badge** ("mark as read"). An interactive element nested in a
+   link is a violation; `SidebarMenuAction` is the row-action slot that already
+   exists.
+8. **No badge as a row's only content**, no badge in place of a label, no badge
+   on a disabled row.
+9. **No `badgeTooltip`** — the rail's tooltip composition already covers it.
+10. **No `maxCells` / `showBadges`** to make the drop or the degradation
+    configurable: the slot budget is documentation, not configuration.
+
+`SidebarMenuBadge`, the primitive, is **deprecated** in favour of this: it is
+`group-data-[collapsible=icon]:hidden`, so its value disappears in the rail, and
+it has no spoken form. It still works, unchanged, for a hand-built `Sidebar`.
 
 ---
 
@@ -208,7 +390,15 @@ Behavior when collapsed on desktop:
 
 - **Labels hide**, they are never squashed or half-clipped: icon and label are
   direct children of the menu button, which the `Sidebar` primitive shrinks to
-  `size-8` / `p-2`.
+  `size-8` / `p-1.5`.
+- **The glyph is 20px in the rail**, against 16px in an expanded row: at 3rem it
+  is the row's only visible content, so it carries what the label carried. The
+  32px pill keeps 6px of padding around it and nothing more —
+  `32 - 2*6 = 20` makes the button's content box exactly the glyph, and that
+  equality is what puts every glyph (icons and initial-letter fallbacks alike)
+  on the panel's centre line, 24px from its edge. See
+  `navTokens.rail` (`src/components/nav-tokens.ts`) and `Sidebar.md` → "Icon-mode geometry": changing
+  either number without the other pushes the whole column off-centre.
 - **Tooltips**: every top-level item shows a tooltip with its title on the right.
   Tooltips are suppressed while the sidebar is expanded and on mobile.
 - **Items with `subItems`** open a dropdown on **click**, anchored to the right of
@@ -229,8 +419,12 @@ opening a menu of the other groups to the right. It replaces the vertical strip
 of 32px squares an earlier version used — those squares were indistinguishable
 from the nav rows right below them, so selector and navigation read as one list.
 
-- **The icon does not move.** Its centre is at (24, 24) from the sidebar edge in
-  _both_ states — measured, expanded and collapsed. That is what makes the swap
+- **The icon does not move, it grows.** Its centre is on the same point in
+  _both_ states — measured, expanded and collapsed — while the glyph itself goes
+  from 16px to the rail's 20px. Paying for those 4px is why the collapsed
+  button is `pt-1.5 gap-0 pb-0.5` and not `pt-2 gap-0.5 pb-0.5`: the top padding
+  holds the centre, the gap covers the remainder, and the column still measures
+  exactly `h-10` (6 + 20 + 0 + 12 + 2). That is what makes the swap
   read as "the label closed and a chevron appeared" rather than a jump, which is
   why there is no transition animating between the two forms: they are different
   DOM trees, and animating that would need FLIP or a shared-layout primitive for
@@ -275,6 +469,228 @@ from the nav rows right below them, so selector and navigation read as one list.
 
 ---
 
+## Hover expansion (`expandOnHover`)
+
+```tsx
+<AppSidebar
+  collapsible="icon"
+  expandOnHover
+  navigation={navigation}
+  onPinnedChange={(pinned) => savePreference(pinned)}
+/>
+```
+
+A third collapse mode on top of `collapsible="icon"`: the pointer (or the focus)
+expands the sidebar **temporarily and as an overlay**, and a **Pin** in the
+header promotes that expansion to permanent. Four states —
+
+| State     | What it is                                                                  |
+| --------- | --------------------------------------------------------------------------- |
+| `mobile`  | Below 768px: the full-screen Sheet, unchanged. No peek, ever.                 |
+| `rail`    | The 3rem icon rail of today.                                                  |
+| `peek`    | Temporarily expanded **over** the page. The layout does not move.             |
+| `pinned`  | Permanently expanded and **pushing** the page — the primitive's `open`.        |
+
+### The peek is an overlay, the pin is a push
+
+This is the whole point of the mode, and the one thing to check first: during a
+peek only the `fixed` panel grows to `--sidebar-width`. The gap element the page
+is laid out against stays at `--sidebar-width-icon`, so **no page content moves**
+— the panel floats over it, with a shadow and a raised z-index. Pinning is the
+ordinary expansion: gap and panel grow together and the main area gives up the
+space.
+
+Implemented in the `Sidebar` primitive, not by widening the panel from outside:
+the children read `state` and the `group-data-[collapsible=icon]:*` rules, not
+the panel's width, so nothing short of a peek-aware `state` gives them their
+expanded rendering. See the `Sidebar` doc for `peek` / `setPeek` and `data-peek`.
+
+Two consequences worth knowing:
+
+- **Tooltips switch off during a peek** on their own — `SidebarMenuButton` hides
+  them whenever `state !== "collapsed"`, and the labels they were standing in for
+  are real text again.
+- **The icon-mode dropdown for sub-items is no longer reachable with a fine
+  pointer** when `expandOnHover` is on: by the time you can click an icon the
+  peek has already swapped in the inline submenu. The dropdown branch is not dead
+  code — it is still what coarse pointers get — but it is not what this mode
+  exercises.
+
+### Preconditions
+
+`expandOnHover` is inert unless **all** of these hold: `collapsible="icon"`,
+viewport ≥ 768px, and a pointer that satisfies
+`(hover: hover) and (pointer: fine)` (read with `matchMedia`, `false` during SSR
+so hydration does not mismatch). Anywhere else the component behaves exactly as
+it does today, and the Pin is not rendered at all — on a touch device it would
+only duplicate `SidebarTrigger`. With a `collapsible` other than `"icon"` the
+prop is ignored **and a warning is logged**.
+
+### Timing
+
+| Delay                | Value  | Why                                                                                                                         |
+| -------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
+| hover in             | 300ms  | A pointer crossing the rail at 800–1200px/s is over it for 50–80ms. 300ms is ~4× an accidental transit — deliberately past the 200–250ms where waiting reads as lag, so the opening feels intentional rather than reactive. Matches the hover out, making the mode symmetric. |
+| hover out            | 300ms  | Grace period: covers the overshoot, the immediate re-entry and the diagonal run to a submenu. Past ~400ms an intentional exit feels sticky. |
+| focus in             | 0ms    | Focus is already deliberate; there is nothing to filter.                                                                     |
+| focus out            | 120ms  | Debounce — **not** courtesy. See "focus and the `<body>` frame" below.                                                        |
+| width                | 200ms `ease-linear` | The primitive's own, deliberately not forked: gap and panel share one declaration and a second curve would desync them during a pin. |
+| overlay shadow       | 160ms, house curve | Not a layout property, so it can take `designTokens.motion.ease` without dragging the width along.               |
+| suppression after unpin | none | Event-based: it lasts until the pointer leaves. A timer would always guess wrong — the user may rest on the Pin for seconds. |
+
+Re-entering inside the grace period resumes the peek **without** paying the
+300ms again: the intent was established on the way in.
+
+Under `prefers-reduced-motion: reduce` the width snaps and the shadow does not
+fade, but **the delays are unchanged**: they filter intention, not movement, and
+removing them would make the sidebar hair-trigger for exactly the users who
+asked for fewer surprises.
+
+### The Pin
+
+- **Where**: its own place at the right end of the header row, sharing the line
+  with `headerContent` (`[headerContent flex-1] [pin]`). With `side="right"` it
+  moves to the left of the row — the panel's inner edge — **and moves with it in
+  the DOM**, so reading order and focus order agree (WCAG 1.3.2). If there is no
+  `headerContent`, the header is mounted for the Pin alone.
+- **When**: visible in `peek` and in `pinned` only. Never in the rail — at 3rem
+  there is no room, and there is nothing yet to keep open.
+- **Hidden, not unmounted.** In the rail the button stays in the tree with
+  `opacity-0 pointer-events-none`, `aria-hidden` and out of the tab order. Two
+  reasons, both second-order: unmounting the control the user has just activated
+  drops the focus on `<body>` — the one state the blur debounce has to ignore, so
+  a keyboard user would be left with the focus nowhere; and mounting a header on
+  the way into a peek would shift every nav row down at the moment the panel is
+  already moving. Reserving the row costs a consumer with no `headerContent` an
+  empty header strip in the rail, which is the trade being made.
+- **After unpinning from the keyboard** the focus moves to the first navigation
+  row, because the button it was on has just gone invisible and `aria-hidden` —
+  no focus ring to see, no name to hear. The rail carries the labels in tooltips
+  from there.
+- **Labels**: `Keep sidebar open` (icon `Pin`) when unpinned, `Collapse sidebar
+to icons` (icon `PinOff`) when pinned, as both the tooltip and the `aria-label`.
+  The icon follows the **action**, not the state: `PinOff` means "click to
+  unpin".
+- **No `aria-pressed`, on purpose.** For an icon button the tooltip _is_ the
+  visible label, so WCAG 2.5.3 (Label in Name) requires the accessible name to
+  contain it. `aria-pressed` would force a name that stays "Keep sidebar open"
+  while pinned, and the state would then be announced twice and in contradiction
+  ("Keep sidebar open, pressed", beside an unpin icon). Two labels say state and
+  outcome in one phrase.
+- **No live region** for expand/collapse. Announcing every pass of the mouse is
+  noise, and for a keyboard user the expansion is already perceivable because the
+  focus is moving through content with accessible names.
+
+### `pinned` is `open`
+
+`pinned` / `defaultPinned` / `onPinnedChange` are a **semantic alias** of the
+provider's `open`, not a parallel state. The Pin button, `Cmd/Ctrl+B`,
+`SidebarTrigger` and the rail all move the same variable, and `onPinnedChange`
+fires for all four. A peek never emits it and **never calls `setOpen`**, so
+hovering does not write the `sidebar_state` cookie — otherwise the consumer's
+persisted preference would be overwritten with noise on every pass of the mouse.
+
+Persistence is the host app's: the library stores nothing beyond the primitive's
+own cookie.
+
+> **Do not control both.** A consumer that drives `SidebarProvider.open` _and_
+> passes `pinned` has two handles on one value. Pick one. Reconciliation keeps
+> them from looping (the component remembers the last value it emitted and does
+> not push back a change the consumer has not yet acknowledged), but two owners
+> of one state is still two owners.
+
+**After an unpin the peek is suppressed** until the pointer leaves the sidebar.
+Without it, unpinning with the cursor still on the panel would reopen a peek
+300ms later and the control would look broken. This holds for the shortcut and
+the rail too. Nothing is suppressed when the pointer is elsewhere — a keyboard
+unpin must not lock the focus route behind a `mouseleave` that will never come.
+
+### Keyboard and focus
+
+- **`focusin` anywhere in the panel expands it immediately**, and the peek stays
+  open while the focus is inside. Closing requires `!hover && !focus &&
+!openMenus`: hover and focus are in **OR**, never in AND.
+- The peek is **not modal**: no focus trap, no `aria-hidden` on the page, no
+  scroll lock, no click-catching overlay.
+- **`Escape` with the focus outside** the sidebar closes the peek immediately.
+  With the focus inside it does nothing of its own — Radix's layers consume it
+  first, and closing would tear the focus out of the panel the user is in.
+- "Focus is inside" means **`:focus-visible`** inside, not merely focused. Radix
+  hands focus back to the trigger when a menu closes, so after a pointer-driven
+  open-and-close the focus would sit inside the panel with the user's attention
+  long gone, holding the peek open until they clicked elsewhere. The browser's
+  own modality heuristic draws that line.
+- **Focus and the `<body>` frame.** Expanding replaces the element that holds
+  focus (the group selector becomes a tab, a dropdown trigger becomes an inline
+  toggle): React unmounts it, `document.activeElement` falls to `<body>` for a
+  frame, and a naive `focusout` handler reads that as "focus left", closes the
+  peek, swaps the tree back and re-fires itself. The 120ms debounce **and**
+  treating `<body>` as "unknown, do not decide" are what break that loop. The
+  existing focus-restoration layout effect puts the focus back on the equivalent
+  control.
+- The peek also closes immediately on `window` blur, on the tab being hidden and
+  on the pointer leaving the document.
+
+### Menus that live in a portal
+
+Radix portals popper content to `document.body`, so a menu opened from inside the
+sidebar is **not** a descendant of the panel: moving the pointer onto it reads as
+having left, and the naive implementation collapses the sidebar out from under
+the open menu. Two defences:
+
+1. While a peek is open, "is the pointer inside?" is answered at the document
+   level and counts any `[data-radix-popper-content-wrapper]` as part of the peek
+   surface.
+2. The peek will not close while a trigger **inside the panel** still has an open
+   popper (`[aria-expanded="true"][data-state="open"]`) — including menus the
+   consumer put in `headerContent` / `footerContent`, whose `onOpenChange` the
+   component cannot hook. When the last one closes, the grace period runs.
+3. **The same latch blocks the peek from opening**, which is the half that is
+   easy to miss. A menu opened from the *rail* is anchored on a trigger that
+   expanding replaces — the icon-mode `DropdownMenuTrigger` becomes an inline
+   toggle — so engaging a peek would tear the open menu down mid-interaction.
+   Reachable two ways: clicking inside the 300ms the hover timer is already
+   counting, and a rail whose peek is suppressed after an unpin. The delay is
+   waited out rather than cancelled, and re-evaluated on the same interval, so
+   the menu closing with the pointer still inside opens the peek — and with the
+   pointer gone, nothing happens.
+
+### Other things worth knowing
+
+- **`SidebarRail` during a peek** rides out to 16rem with the panel and floats
+  over the main area. That is correct: clicking it pins. The resize cursor flips
+  direction with it, which is also correct.
+- **`variant="inset"` / `"floating"`** need the peek override in two places, and
+  both are done: the gap keeps the per-variant
+  `calc(var(--sidebar-width-icon) + 1rem)` formula, and `SidebarInset`'s left
+  margin is re-anchored to `data-peek` because it keys off `data-state`, which a
+  peek flips to `"expanded"`.
+- **z-index**: the panel is raised to `z-30` while peeking so it clears the
+  sticky headers the template layouts use, and dropped back afterwards. This
+  value is a working default, not a considered answer — the right one depends on
+  the host app's stacking context, which the library cannot know.
+- **`side="right"`** is fully mirrored: the panel is anchored to the right edge,
+  so a peek grows **inward** over the page and never off the viewport, and the
+  Pin follows to the panel's inner (left) end. `dir="rtl"` is a different
+  question and is **not** supported — the primitive positions with physical
+  `left`/`right`, which predates this mode.
+- **Scroll position** in `SidebarContent` is preserved across the rail↔expanded
+  swap; the content changes height as inline submenus come and go, and a long
+  list would otherwise lose the user's place.
+- **Nothing in ARIA reflects the peek**, by design: it is pointer-bound and
+  temporary, and announcing it would have a screen reader narrate every pass of
+  the mouse. `SidebarTrigger` and `SidebarRail` carry no `aria-expanded` at all,
+  and the Pin's label follows `pinned`. The one measured residue is Radix's
+  hidden `role="tooltip"` span: suppression hides the tooltip's bubble but leaves
+  Radix believing it is open, so a row's `aria-describedby` can still point at a
+  label that is now also visible text. Closing it properly means taking ownership
+  of the tooltip's `open` away from the primitive, which regressed the collapsed
+  rail's tooltips when tried — left as is deliberately.
+- **One `SidebarProvider` per sidebar.** Two would register two `Cmd/Ctrl+B`
+  listeners and, now, two independent peeks.
+
+---
+
 ## Mobile menu (`<768px`)
 
 Below 768px (the `useIsMobile` breakpoint) `AppSidebar` **replaces** the desktop
@@ -301,7 +717,14 @@ Anatomy, level 0:
   aligned. There is no initial-letter fallback here (unlike desktop icon mode,
   where the icon is the only affordance).
 - A chevron on the right marks rows that have `subItems` — and only those.
-- The active row uses `designTokens.navItem.selected`: a `bg-d-primary/10`
+- A **badge** sits between the label and the chevron, at full capacity, on both
+  the level-0 rows and the level-1 sub-rows; a group's own badge renders on its
+  uppercase heading. A level-0 parent with no badge of its own shows a dot when
+  one of its children is badged — its children live behind the drill, so this is
+  the collapsed-parent rule again. The drilled level's `<h2>` never takes one:
+  the parent's badge is on the row the user just tapped, and the children carry
+  their own.
+- The active row uses `navTokens.item.selected`: a `bg-d-primary/10`
   surface tint, a full-contrast `text-d-foreground` label, and a 2px left bar as
   a second, non-colour channel. A parent row is tinted when **any** of its
   `subItems` is active, so level 0 still shows where you are on a sub-page;
@@ -310,9 +733,20 @@ Anatomy, level 0:
   open** — Radix would otherwise focus the first focusable node in it, which for
   a search field means raising the keyboard over the menu. Focus goes to the
   panel itself, and returns to whatever opened the sheet when it closes.
+- The sheet's close button floats over the top-right corner, so the header
+  reserves **48px on each side** for it — symmetrically, so that a
+  `headerContent` the consumer centres (a logo, as the template does) stays on
+  the panel's centre line instead of being pushed off it by a one-sided
+  reserve. Full-width header content is inset by that reserve; the back bar of
+  a drilled level is left-aligned and only reserves on the right.
 - `navigationFooter` is detached from the groups above it as the "system" block
-  of a native Settings list; `footerContent` is the last block, and the panel
-  reserves `env(safe-area-inset-bottom)` below it for the home indicator.
+  of a native Settings list, and **sits at the bottom of the scroll area** the
+  way the desktop panel's does: when `navigation` is shorter than the panel the
+  block drops to the bottom instead of trailing the last group; when it is
+  longer the block simply scrolls after it. It scrolls with the list either way
+  — it is not pinned over it, so it never covers a row. `footerContent` is the
+  last block, and the panel reserves `env(safe-area-inset-bottom)` below it for
+  the home indicator.
 - Above 640px the column is capped and centred: a full-bleed card would leave
   the chevron a screen-width away from its label.
 
@@ -402,6 +836,65 @@ export function Layout() {
 }
 ```
 
+### With badges
+
+```tsx
+const navigation = [
+  {
+    title: "Generale",
+    // A group's own badge. Never a sum over its items.
+    badge: "BETA",
+    badgeLabel: "gruppo in beta",
+    items: [
+      { title: "Dashboard", url: "/", isActive: true, iconName: "Home" },
+      // A count. Over 99 renders "99+"; 0 renders nothing.
+      {
+        title: "Documenti",
+        url: "/docs",
+        iconName: "FileText",
+        badge: 120,
+        badgeLabel: "oltre 99 documenti non letti",
+      },
+      // Short text. Degrades to a dot in the rail and in the bottom bar.
+      {
+        title: "Archivio",
+        url: "/archive",
+        iconName: "Archive",
+        badge: "NEW",
+        badgeLabel: "sezione nuova",
+      },
+      // A dot. `badgeLabel` is what keeps it from being silent.
+      {
+        title: "Notifiche",
+        url: "/alerts",
+        iconName: "Bell",
+        badge: true,
+        badgeLabel: "hai notifiche non lette",
+      },
+      // No badge of its own: a dot while the submenu is shut, nothing once it
+      // is open, and never the sum of its children.
+      {
+        title: "Messaggi",
+        url: "#",
+        iconName: "MessageSquare",
+        subItems: [
+          {
+            title: "Inbox",
+            url: "/inbox",
+            iconName: "Inbox",
+            badge: 12,
+            badgeLabel: "12 messaggi non letti",
+          },
+          { title: "Inviati", url: "/sent", iconName: "Send" },
+        ],
+      },
+    ],
+  },
+];
+
+<AppSidebar navigation={navigation} collapsible="icon" />;
+```
+
 ### With Header/Footer Content
 
 ```tsx