Sidebar: peek & control gaps (transparent inset peek, reduced-motion, external control, peek state, backdrop)

This issue collects several related Sidebar gaps found while building an
inset sidebar with peekOnHover. The first is a concrete visual bug; the rest
are behaviour/API gaps that force consumers to reach around the component.

---

1. Peek overlay is transparent under variant="inset"

Summary

When a Sidebar uses variant="inset" together with peekOnHover, the peek
overlay renders with a transparent background. Because peek lifts the sidebar
above the page content (shadow + z-index), the content behind it shows
straight through, making the nav unreadable.

The same feature works correctly on variant="floating" and variant="plain",
where the sidebar keeps an opaque background — so this looks like the inset
case was missed in the peek path.

Reproduction

<Sidebar variant="inset" collapsible="hidden" peekOnHover defaultOpen>
  <Sidebar.Header>…</Sidebar.Header>
  <Sidebar.Main>
    <Sidebar.Item leadingIcon={<Home />}>Home</Sidebar.Item>
    {/* …more items… */}
  </Sidebar.Main>
</Sidebar>

1. Collapse the sidebar (it hides).
2. Hover the collapsed edge to trigger the peek.
3. The revealed sidebar is transparent — page content is visible through it.

Happens with collapsible="icon" too; inset is the deciding factor.

Root cause

In the compiled sidebar CSS:

• Base rule sets an opaque background:
  [data-slot="sidebar"] { background: var(--rs-color-background-base-primary) }
• inset overrides it to transparent (correct while docked):
  [data-variant="inset"] { background: transparent }
• The peek rule adds elevation but never restores a background:
  [data-peeking] { box-shadow: var(--rs-shadow-lifted); z-index: …; width: … }

floating never zeroes the background, so its peek stays opaque — hence the
inconsistency.

Suggested fix

Give the peeking overlay an opaque background in the peek rule, independent of
variant:

[data-peeking] {
  background: var(--rs-color-background-base-primary);
}

---

2. prefers-reduced-motion not honored for the sidebar's own transitions

Apsara already gates dialog, accordion, and announcement-bar transitions behind
@media (prefers-reduced-motion: no-preference), but the sidebar's
width / margin peek & collapse transition on the root is unconditional:

[data-slot="sidebar"] {
  transition: width var(--rs-duration-normal) var(--rs-ease-out),
              margin var(--rs-duration-normal) var(--rs-ease-out);
}

Users who request reduced motion still get the animated peek/collapse.

Suggested fix: wrap the root's transition in the same
prefers-reduced-motion: no-preference guard already used elsewhere in the
library, so it's consistent.

---

3. Cannot control the sidebar from outside its subtree

Sidebar.Trigger reads the internal useSidebar() context, so it only works
inside <Sidebar>. There's no supported way to toggle the sidebar from
elsewhere in the app — e.g. a top bar, breadcrumb row, or header rendered
outside the sidebar tree.

Consumers who want an external toggle must lift open / onOpenChange into
their own state and re-implement the control, duplicating what the sidebar
already manages.

Suggested options (any one):

• An imperative handle via ref (sidebarRef.current.toggle() / open() /
  close()).
• A standalone trigger that targets a sidebar by id.
• Documenting open / onOpenChange as the supported pattern for external
  control (if that's the intended answer).

---

4. Peek state (isPeeking) is not exposed to the parent

isPeeking is available on the context via useSidebar(), but only to
descendants inside the sidebar. A parent can't react to a peek starting or
ending — e.g. to render a backdrop, coordinate other UI, or fire analytics.

Today the only way to observe a peek from outside is a CSS
:has([data-peeking]) hack.

Suggested fix: add an onPeekChange(isPeeking: boolean) callback prop,
mirroring onOpenChange.

---

5. No backdrop option for peekOnHover

When peeking, the sidebar floats above the content with only a shadow. There's
no built-in way to dim or scrim the app behind the peek — a common pattern for
hover-drawers, and it helps the floating panel read as a distinct layer.

Suggested fix: an opt-in peekBackdrop (boolean, or a slot) that renders a
backdrop behind the peeking sidebar. Consumers style the look (color/blur);
Apsara owns the show/hide wiring, which it's uniquely able to tie to the
internal peek state.

Start at the Sidebar root styling and the Sidebar, Sidebar.Trigger, and useSidebar entry points. Compare the inset peek rules with floating and plain variants, then inspect the existing reduced-motion guards and current context state. Done means the visual bug and motion behavior are addressed, while the external control, peek callback, and backdrop API decisions are implemented consistently.