From 518b5ca5425ea765aff38a2776dc36739dcd2a3b Mon Sep 17 00:00:00 2001
From: Rohan Chakraborty <irohan1999@gmail.com>
Date: Tue, 29 Sep 2026 15:42:56 +0530
Subject: [PATCH 1/3] feat: [sidebar] add onPeekChange and peekBackdrop, fix
 inset peek background

---
 .../content/docs/components/sidebar/demo.ts   | 10 ++++++++
 .../content/docs/components/sidebar/index.mdx | 24 +++++++++++++++++++
 .../content/docs/components/sidebar/props.ts  |  8 +++++++
 .../sidebar/__tests__/data-slots.test.tsx     | 18 +++++++++++++-
 .../sidebar/__tests__/sidebar.test.tsx        | 14 +++++++++++
 .../components/sidebar/sidebar-root.tsx       | 19 +++++++++++++++
 .../components/sidebar/sidebar.module.css     | 12 ++++++++++
 7 files changed, 104 insertions(+), 1 deletion(-)

diff --git a/apps/www/src/content/docs/components/sidebar/demo.ts b/apps/www/src/content/docs/components/sidebar/demo.ts
index 4a638a6b5..406097bcf 100644
--- a/apps/www/src/content/docs/components/sidebar/demo.ts
+++ b/apps/www/src/content/docs/components/sidebar/demo.ts
@@ -393,6 +393,16 @@ export const peekOnHoverDemo = {
             </Sidebar.Group>
           </Sidebar.Main>
         </Sidebar>`)
+    },
+    {
+      name: 'Backdrop',
+      code: sidebarLayout(`<Sidebar defaultOpen={false} variant="inset" peekOnHover peekBackdrop>
+          <Sidebar.Main>
+            <Sidebar.Item href="#" leadingIcon={<Building2 size={16} strokeWidth={1.5} />}>Overview</Sidebar.Item>
+            <Sidebar.Item href="#" leadingIcon={<Bell size={16} strokeWidth={1.5} />} active>Dashboard</Sidebar.Item>
+            <Sidebar.Item href="#" leadingIcon={<FilterIcon width={16} height={16} />}>Analytics</Sidebar.Item>
+          </Sidebar.Main>
+        </Sidebar>`)
     }
   ],
   style: styleDemo
diff --git a/apps/www/src/content/docs/components/sidebar/index.mdx b/apps/www/src/content/docs/components/sidebar/index.mdx
index 2f5eea99b..abe9167bc 100644
--- a/apps/www/src/content/docs/components/sidebar/index.mdx
+++ b/apps/www/src/content/docs/components/sidebar/index.mdx
@@ -91,6 +91,24 @@ The sidebar expands and collapses, animating between the two. Collapsed keeps ic
 
 <Demo data={stateDemo} />
 
+### External control
+
+`Sidebar.Trigger` and `useSidebar` work only inside `<Sidebar>`. To toggle the sidebar from elsewhere, for example a top bar, control it with `open` and `onOpenChange`:
+
+```tsx
+const [open, setOpen] = useState(true);
+
+<IconButton
+  aria-label="Toggle sidebar"
+  aria-expanded={open}
+  aria-controls="app-sidebar"
+  onClick={() => setOpen(!open)}
+>
+  <PanelLeft />
+</IconButton>
+<Sidebar id="app-sidebar" open={open} onOpenChange={setOpen}>…</Sidebar>
+```
+
 ### Non-collapsible
 
 Set `collapsible="none"` to hide the resize handle and prevent the sidebar from being collapsed or expanded.
@@ -114,6 +132,11 @@ so hover the thin strip at the edge instead, as the "Hidden" tab below shows.
 The peek waits 100ms so it does not fire when the mouse only passes over.
 Change that with `peekDelay`.
 
+The overlay always has an opaque background, also with `variant="inset"`.
+Set `peekBackdrop` to dim the page behind it, as the "Backdrop" tab shows. Style
+the backdrop with the `sidebar-backdrop` slot. `onPeekChange` reports when a
+peek starts or ends, for UI outside the sidebar.
+
 <Demo data={peekOnHoverDemo} />
 
 ### Custom tooltip message
@@ -216,6 +239,7 @@ Every rendered part carries a stable `data-slot` attribute for [styling and test
 |------|---------|
 | `sidebar` | The root `<aside>` |
 | `sidebar-toggle` | The resize handle that expands/collapses the sidebar (when `collapsible`) |
+| `sidebar-backdrop` | Backdrop behind a peeking sidebar (when `peekBackdrop`) |
 | `sidebar-trigger` | `Sidebar.Trigger` button |
 | `sidebar-header` | `Sidebar.Header` container |
 | `sidebar-main` | `Sidebar.Main` container |
diff --git a/apps/www/src/content/docs/components/sidebar/props.ts b/apps/www/src/content/docs/components/sidebar/props.ts
index d1038ac7e..48fa3bdef 100644
--- a/apps/www/src/content/docs/components/sidebar/props.ts
+++ b/apps/www/src/content/docs/components/sidebar/props.ts
@@ -36,6 +36,14 @@ export interface SidebarRootProps {
    */
   peekDelay?: number;
 
+  /** Called when a hover peek starts or ends. */
+  onPeekChange?: (isPeeking: boolean) => void;
+
+  /** Renders a backdrop behind the sidebar while it peeks.
+   * @default false
+   */
+  peekBackdrop?: boolean;
+
   /** Position of the Sidebar.
    * @default "left"
    */
diff --git a/packages/raystack/components/sidebar/__tests__/data-slots.test.tsx b/packages/raystack/components/sidebar/__tests__/data-slots.test.tsx
index e92ef3a74..ccfdc4da0 100644
--- a/packages/raystack/components/sidebar/__tests__/data-slots.test.tsx
+++ b/packages/raystack/components/sidebar/__tests__/data-slots.test.tsx
@@ -1,4 +1,4 @@
-import { fireEvent, render, screen } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { describe, expect, it } from 'vitest';
 import { expectSlots, getSlot } from '~/test-utils/data-slots';
 import { Sidebar } from '../sidebar';
@@ -53,6 +53,22 @@ describe('Sidebar data-slot contract', () => {
     expect(getSlot(container, 'sidebar-toggle')).toBeNull();
   });
 
+  it('exposes the backdrop slot only while peeking with peekBackdrop', async () => {
+    const { container } = render(
+      <Sidebar open={false} peekOnHover peekBackdrop />
+    );
+    expect(getSlot(container, 'sidebar-backdrop')).toBeNull();
+
+    const nav = screen.getByRole('navigation');
+    fireEvent.mouseEnter(nav);
+    await waitFor(() =>
+      expect(getSlot(container, 'sidebar-backdrop')).not.toBeNull()
+    );
+
+    fireEvent.mouseLeave(nav);
+    expect(getSlot(container, 'sidebar-backdrop')).toBeNull();
+  });
+
   it('exposes trailing icon slot on a group when provided', () => {
     const { container } = render(
       <Sidebar>
diff --git a/packages/raystack/components/sidebar/__tests__/sidebar.test.tsx b/packages/raystack/components/sidebar/__tests__/sidebar.test.tsx
index 99bb3da4f..381e2772d 100644
--- a/packages/raystack/components/sidebar/__tests__/sidebar.test.tsx
+++ b/packages/raystack/components/sidebar/__tests__/sidebar.test.tsx
@@ -323,6 +323,20 @@ describe('Sidebar', () => {
       );
     });
 
+    it('reports peek start and end via onPeekChange', async () => {
+      const onPeekChange = vi.fn();
+      render(<Sidebar open={false} peekOnHover onPeekChange={onPeekChange} />);
+      expect(onPeekChange).not.toHaveBeenCalled();
+
+      const nav = screen.getByRole('navigation');
+      fireEvent.mouseEnter(nav);
+      await waitFor(() => expect(onPeekChange).toHaveBeenCalledWith(true));
+
+      fireEvent.mouseLeave(nav);
+      await waitFor(() => expect(onPeekChange).toHaveBeenLastCalledWith(false));
+      expect(onPeekChange).toHaveBeenCalledTimes(2);
+    });
+
     it('pins the sidebar open when the handle is clicked while peeking', async () => {
       const onOpenChange = vi.fn();
       render(
diff --git a/packages/raystack/components/sidebar/sidebar-root.tsx b/packages/raystack/components/sidebar/sidebar-root.tsx
index e10dec210..b0bd6d88f 100644
--- a/packages/raystack/components/sidebar/sidebar-root.tsx
+++ b/packages/raystack/components/sidebar/sidebar-root.tsx
@@ -96,6 +96,13 @@ export interface SidebarRootProps extends ComponentProps<'aside'> {
    * @default 100
    */
   peekDelay?: number;
+  /** Called when a hover peek starts or ends. */
+  onPeekChange?: (isPeeking: boolean) => void;
+  /**
+   * Renders a backdrop behind the sidebar while it peeks.
+   * @default false
+   */
+  peekBackdrop?: boolean;
   /** Tooltip shown when hovering the collapse/expand handle. */
   collapseTooltip?: ReactNode;
   open?: boolean;
@@ -118,6 +125,8 @@ export function SidebarRoot({
   collapsible = 'icon',
   peekOnHover = false,
   peekDelay = DEFAULT_PEEK_DELAY,
+  onPeekChange,
+  peekBackdrop = false,
   collapseTooltip,
   defaultOpen = true,
   children,
@@ -187,6 +196,13 @@ export function SidebarRoot({
     setIsPeeking(false);
   }, [open]);
 
+  const lastPeekRef = useRef(false);
+  useEffect(() => {
+    if (lastPeekRef.current === isPeeking) return;
+    lastPeekRef.current = isPeeking;
+    onPeekChange?.(isPeeking);
+  }, [isPeeking, onPeekChange]);
+
   // data-open/data-closed drive the visuals, so a peek counts as open,
   // every collapse-hiding CSS rule turns off during a peek for free. The
   // real state stays in `open` (and the toggle controls' aria-expanded).
@@ -206,6 +222,9 @@ export function SidebarRoot({
       }}
     >
       <SidebarPopupContext value={handlePopupOpenChange}>
+        {peekBackdrop && isPeeking && (
+          <div className={styles.backdrop} data-slot='sidebar-backdrop' />
+        )}
         <aside
           id={sidebarId}
           className={cx(styles.root, className)}
diff --git a/packages/raystack/components/sidebar/sidebar.module.css b/packages/raystack/components/sidebar/sidebar.module.css
index d10188979..a00bb04ab 100644
--- a/packages/raystack/components/sidebar/sidebar.module.css
+++ b/packages/raystack/components/sidebar/sidebar.module.css
@@ -72,6 +72,8 @@
   width: var(--sidebar-open-width);
   z-index: var(--rs-z-index-portal);
   box-shadow: var(--rs-shadow-lifted);
+  /* The inset variant is transparent, and the overlay must hide the content under it. */
+  background: var(--rs-color-background-base-primary);
 }
 
 .root[data-peeking][data-position="left"] {
@@ -85,6 +87,16 @@
   margin-left: calc(var(--sidebar-collapsed-width) - var(--sidebar-open-width));
 }
 
+/* Same z-index as the peeking sidebar. The backdrop comes first in the DOM,
+   so it paints below it. The peek ends on mouse leave, so it never takes clicks. */
+.backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: var(--rs-z-index-portal);
+  background-color: var(--rs-color-overlay);
+  pointer-events: none;
+}
+
 .header {
   gap: var(--rs-space-3);
   padding: 0 var(--rs-space-4);

From e87bc03c0000bcec4228eb93ce474a44bee18782 Mon Sep 17 00:00:00 2001
From: Rohan Chakraborty <irohan1999@gmail.com>
Date: Tue, 29 Sep 2026 16:38:57 +0530
Subject: [PATCH 2/3] refactor: [sidebar] drop peekBackdrop

onPeekChange lets consumers render their own backdrop. The fixed backdrop also escaped the sidebar's container. Link the Trigger note to the external control section instead of repeating it.
---
 .../content/docs/components/sidebar/demo.ts    | 10 ----------
 .../content/docs/components/sidebar/index.mdx  |  9 +++------
 .../content/docs/components/sidebar/props.ts   |  5 -----
 .../sidebar/__tests__/data-slots.test.tsx      | 18 +-----------------
 .../components/sidebar/sidebar-root.tsx        |  9 ---------
 .../components/sidebar/sidebar.module.css      | 10 ----------
 6 files changed, 4 insertions(+), 57 deletions(-)

diff --git a/apps/www/src/content/docs/components/sidebar/demo.ts b/apps/www/src/content/docs/components/sidebar/demo.ts
index 406097bcf..4a638a6b5 100644
--- a/apps/www/src/content/docs/components/sidebar/demo.ts
+++ b/apps/www/src/content/docs/components/sidebar/demo.ts
@@ -393,16 +393,6 @@ export const peekOnHoverDemo = {
             </Sidebar.Group>
           </Sidebar.Main>
         </Sidebar>`)
-    },
-    {
-      name: 'Backdrop',
-      code: sidebarLayout(`<Sidebar defaultOpen={false} variant="inset" peekOnHover peekBackdrop>
-          <Sidebar.Main>
-            <Sidebar.Item href="#" leadingIcon={<Building2 size={16} strokeWidth={1.5} />}>Overview</Sidebar.Item>
-            <Sidebar.Item href="#" leadingIcon={<Bell size={16} strokeWidth={1.5} />} active>Dashboard</Sidebar.Item>
-            <Sidebar.Item href="#" leadingIcon={<FilterIcon width={16} height={16} />}>Analytics</Sidebar.Item>
-          </Sidebar.Main>
-        </Sidebar>`)
     }
   ],
   style: styleDemo
diff --git a/apps/www/src/content/docs/components/sidebar/index.mdx b/apps/www/src/content/docs/components/sidebar/index.mdx
index abe9167bc..cccb4656b 100644
--- a/apps/www/src/content/docs/components/sidebar/index.mdx
+++ b/apps/www/src/content/docs/components/sidebar/index.mdx
@@ -132,10 +132,8 @@ so hover the thin strip at the edge instead, as the "Hidden" tab below shows.
 The peek waits 100ms so it does not fire when the mouse only passes over.
 Change that with `peekDelay`.
 
-The overlay always has an opaque background, also with `variant="inset"`.
-Set `peekBackdrop` to dim the page behind it, as the "Backdrop" tab shows. Style
-the backdrop with the `sidebar-backdrop` slot. `onPeekChange` reports when a
-peek starts or ends, for UI outside the sidebar.
+`onPeekChange` reports when a peek starts or ends, for example to dim the page
+behind the sidebar.
 
 <Demo data={peekOnHoverDemo} />
 
@@ -219,7 +217,7 @@ The footer section is a container that accepts all `div` props. It's commonly us
 
 A button that toggles the sidebar open/closed. It works whether the Sidebar is controlled or uncontrolled, so you can drop it into a header without wiring up any state yourself. It accepts all `IconButton` props (e.g. `size`) plus the ones below.
 
-*Note: disabled automatically when the Sidebar has `collapsible="none"`. If you use `collapsible="hidden"`, don't place `Sidebar.Trigger` inside `Sidebar.Header`/`Main`/`Footer`, because those sections are hidden along with the rest of the collapsed content, taking the trigger with them. Render it as a direct child of `<Sidebar>` instead, or drive `open`/`onOpenChange` yourself with a toggle button that lives outside `<Sidebar>` entirely (e.g. in your app's top bar).*
+*Note: disabled automatically when the Sidebar has `collapsible="none"`. If you use `collapsible="hidden"`, don't place `Sidebar.Trigger` inside `Sidebar.Header`/`Main`/`Footer`, because those sections are hidden along with the rest of the collapsed content, taking the trigger with them. Render it as a direct child of `<Sidebar>` instead, or use [external control](#external-control).*
 
 <auto-type-table path="./props.ts" name="SidebarTriggerProps" />
 
@@ -239,7 +237,6 @@ Every rendered part carries a stable `data-slot` attribute for [styling and test
 |------|---------|
 | `sidebar` | The root `<aside>` |
 | `sidebar-toggle` | The resize handle that expands/collapses the sidebar (when `collapsible`) |
-| `sidebar-backdrop` | Backdrop behind a peeking sidebar (when `peekBackdrop`) |
 | `sidebar-trigger` | `Sidebar.Trigger` button |
 | `sidebar-header` | `Sidebar.Header` container |
 | `sidebar-main` | `Sidebar.Main` container |
diff --git a/apps/www/src/content/docs/components/sidebar/props.ts b/apps/www/src/content/docs/components/sidebar/props.ts
index 48fa3bdef..9c8fe01b8 100644
--- a/apps/www/src/content/docs/components/sidebar/props.ts
+++ b/apps/www/src/content/docs/components/sidebar/props.ts
@@ -39,11 +39,6 @@ export interface SidebarRootProps {
   /** Called when a hover peek starts or ends. */
   onPeekChange?: (isPeeking: boolean) => void;
 
-  /** Renders a backdrop behind the sidebar while it peeks.
-   * @default false
-   */
-  peekBackdrop?: boolean;
-
   /** Position of the Sidebar.
    * @default "left"
    */
diff --git a/packages/raystack/components/sidebar/__tests__/data-slots.test.tsx b/packages/raystack/components/sidebar/__tests__/data-slots.test.tsx
index ccfdc4da0..e92ef3a74 100644
--- a/packages/raystack/components/sidebar/__tests__/data-slots.test.tsx
+++ b/packages/raystack/components/sidebar/__tests__/data-slots.test.tsx
@@ -1,4 +1,4 @@
-import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { fireEvent, render, screen } from '@testing-library/react';
 import { describe, expect, it } from 'vitest';
 import { expectSlots, getSlot } from '~/test-utils/data-slots';
 import { Sidebar } from '../sidebar';
@@ -53,22 +53,6 @@ describe('Sidebar data-slot contract', () => {
     expect(getSlot(container, 'sidebar-toggle')).toBeNull();
   });
 
-  it('exposes the backdrop slot only while peeking with peekBackdrop', async () => {
-    const { container } = render(
-      <Sidebar open={false} peekOnHover peekBackdrop />
-    );
-    expect(getSlot(container, 'sidebar-backdrop')).toBeNull();
-
-    const nav = screen.getByRole('navigation');
-    fireEvent.mouseEnter(nav);
-    await waitFor(() =>
-      expect(getSlot(container, 'sidebar-backdrop')).not.toBeNull()
-    );
-
-    fireEvent.mouseLeave(nav);
-    expect(getSlot(container, 'sidebar-backdrop')).toBeNull();
-  });
-
   it('exposes trailing icon slot on a group when provided', () => {
     const { container } = render(
       <Sidebar>
diff --git a/packages/raystack/components/sidebar/sidebar-root.tsx b/packages/raystack/components/sidebar/sidebar-root.tsx
index b0bd6d88f..de6374c8b 100644
--- a/packages/raystack/components/sidebar/sidebar-root.tsx
+++ b/packages/raystack/components/sidebar/sidebar-root.tsx
@@ -98,11 +98,6 @@ export interface SidebarRootProps extends ComponentProps<'aside'> {
   peekDelay?: number;
   /** Called when a hover peek starts or ends. */
   onPeekChange?: (isPeeking: boolean) => void;
-  /**
-   * Renders a backdrop behind the sidebar while it peeks.
-   * @default false
-   */
-  peekBackdrop?: boolean;
   /** Tooltip shown when hovering the collapse/expand handle. */
   collapseTooltip?: ReactNode;
   open?: boolean;
@@ -126,7 +121,6 @@ export function SidebarRoot({
   peekOnHover = false,
   peekDelay = DEFAULT_PEEK_DELAY,
   onPeekChange,
-  peekBackdrop = false,
   collapseTooltip,
   defaultOpen = true,
   children,
@@ -222,9 +216,6 @@ export function SidebarRoot({
       }}
     >
       <SidebarPopupContext value={handlePopupOpenChange}>
-        {peekBackdrop && isPeeking && (
-          <div className={styles.backdrop} data-slot='sidebar-backdrop' />
-        )}
         <aside
           id={sidebarId}
           className={cx(styles.root, className)}
diff --git a/packages/raystack/components/sidebar/sidebar.module.css b/packages/raystack/components/sidebar/sidebar.module.css
index a00bb04ab..67f9202a5 100644
--- a/packages/raystack/components/sidebar/sidebar.module.css
+++ b/packages/raystack/components/sidebar/sidebar.module.css
@@ -87,16 +87,6 @@
   margin-left: calc(var(--sidebar-collapsed-width) - var(--sidebar-open-width));
 }
 
-/* Same z-index as the peeking sidebar. The backdrop comes first in the DOM,
-   so it paints below it. The peek ends on mouse leave, so it never takes clicks. */
-.backdrop {
-  position: fixed;
-  inset: 0;
-  z-index: var(--rs-z-index-portal);
-  background-color: var(--rs-color-overlay);
-  pointer-events: none;
-}
-
 .header {
   gap: var(--rs-space-3);
   padding: 0 var(--rs-space-4);

From 2f9e0daa33f19a0d3a1336f5ec46585c20186cc0 Mon Sep 17 00:00:00 2001
From: Rohan Chakraborty <irohan1999@gmail.com>
Date: Mon, 5 Oct 2026 02:26:22 +0530
Subject: [PATCH 3/3] fix: [sidebar] scope peek background to inset variant

---
 packages/raystack/components/sidebar/sidebar.module.css | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/raystack/components/sidebar/sidebar.module.css b/packages/raystack/components/sidebar/sidebar.module.css
index 67f9202a5..58c1f3b0e 100644
--- a/packages/raystack/components/sidebar/sidebar.module.css
+++ b/packages/raystack/components/sidebar/sidebar.module.css
@@ -72,7 +72,10 @@
   width: var(--sidebar-open-width);
   z-index: var(--rs-z-index-portal);
   box-shadow: var(--rs-shadow-lifted);
-  /* The inset variant is transparent, and the overlay must hide the content under it. */
+}
+
+/* Inset is transparent, so its overlay needs a background to hide the content under it. */
+.root[data-peeking][data-variant="inset"] {
   background: var(--rs-color-background-base-primary);
 }