feat(sidebar): add SidebarPersistentContent and inert closed content

Co-Authored-By: Claude <noreply@anthropic.com>

Author: frankieyan

src/sidebar/sidebar.mdx

@@ -35,7 +35,8 @@ styles the real elements while the provider holds state and behavior.
 | Part | Renders | Owns |
 | --- | --- | --- |
 | \`Sidebar\` | the modal backdrop only (a sibling of the panel) | All controlled state and behavior: open, overlay, width and bounds, dismiss; derives the overlay state; provides context |
-| \`SidebarContent\` | the panel element (a neutral \`<div>\` with \`role="dialog"\` when needed) | Positioning, the slide / collapse transition, dialog semantics, the committed width, the focus trap and assistive-tech hiding while modal, and panel-scoped Escape-to-dismiss |
+| \`SidebarContent\` | the panel element (a neutral \`<div>\` with \`role="dialog"\` when needed) | Positioning, the slide / collapse transition, dialog semantics, the committed width, the focus trap and assistive-tech hiding while modal, making its contents \`inert\` while closed, and panel-scoped Escape-to-dismiss |
+| \`SidebarPersistentContent\` | an optional slot inside the panel | A control that stays live while the sidebar is closed (e.g. a collapse toggle): kept out of the closed-state \`inert\`, while it rides the collapse transition and joins the focus trap |
 | \`SidebarResizeHandle\` | a \`role="separator"\` | The pointer and keyboard resize affordance and its ARIA; self-positions on the inner edge from \`align\` |
 `}</Markdown>
 
@@ -187,6 +188,27 @@ provider. Set the same `id` on `Sidebar` that the trigger points its
 </button>
 ```
 
+## A control that stays live while closed
+
+While a sidebar is closed, its contents are made `inert`, so off-screen controls leave the tab order and the accessibility tree. `SidebarPersistentContent` is the exception: a control placed in it stays usable while the sidebar is closed, the canonical case being a collapse toggle that peeks out of the slid-off panel and reopens it. Unlike the external trigger above, this is for a toggle that belongs _in_ the panel.
+
+<Canvas of={SidebarStories.CollapsibleNav} />
+
+Its children render inside the panel, so they ride the collapse transition and join the focus trap when modal, but outside the closed-state `inert`. It works at any nesting depth, so a toggle already living deep in the content does not need hoisting.
+
+```tsx
+<SidebarContent aria-label="Main navigation">
+    <SidebarPersistentContent>
+        <button aria-expanded={isOpen} aria-controls="sidebar" data-no-autofocus onClick={toggle}>
+            {/* your icon / tooltip */}
+        </button>
+    </SidebarPersistentContent>
+    <nav aria-label="Main navigation">{/* nav content */}</nav>
+</SidebarContent>
+```
+
+When the panel opens as a modal, the trap's initial focus goes to the first focusable, often the persistent control. Whether that is wanted is the consumer's call: add `data-no-autofocus` to your control (a react-focus-lock attribute) to keep a toggle from grabbing it, the way `Modal` opts its close button out, or `data-autofocus` to send initial focus to a specific element; the control stays tabbable either way. The consumer owns the control, its `aria-*`, and its positioning (e.g. a peek offset while collapsed).
+
 ## Left and right sidebars
 
 A left nav and a right pane around the main absorber is the full shell contract.
@@ -256,3 +278,9 @@ CSS custom properties, set on `SidebarContent` (or any ancestor).
   or tooltip) keeps it.
 - The resize handle is a focusable `separator` while open, and leaves the tab
   order and the accessibility tree while closed.
+- While closed, the panel's contents are made `inert`, so off-screen controls
+  leave the tab order and the accessibility tree. A control in
+  `SidebarPersistentContent` is exempt and stays interactive. When the panel opens
+  as a modal it receives initial focus by default (it is first in the trap), so add
+  `data-no-autofocus` to it if it should not grab focus, as `Modal` does for its
+  close button.

src/sidebar/sidebar.module.css

@@ -1,6 +1,7 @@
 :root {
     /* Overlay layering and viewport behaviour. */
     --reactist-sidebar-overlay-z-index: 40;
+    --reactist-sidebar-collapsed-z-index: 1;
     --reactist-sidebar-overlay-viewport-margin: 0px;
     --reactist-sidebar-overlay-inset-block: 0px;
     --reactist-sidebar-overlay-inset-inline: 0px;
@@ -51,6 +52,15 @@
     margin-inline-end: calc(-1 * var(--reactist-sidebar-width, 0px));
 }
 
+/*
+ * Collapsed + docked, the panel's own `contain: layout` traps a persistent
+ * control's z-index in the panel's stacking context, so it paints under a main
+ * that is itself a stacking context. Lift the panel to keep the control visible.
+ */
+.panel[data-overlay='false'][data-state='closed'] {
+    z-index: var(--reactist-sidebar-collapsed-z-index);
+}
+
 /*
  * Overlay: the panel floats over the content layer, anchored to its align edge
  * and capped to the viewport. It slides off-edge with a compositor-only
@@ -92,6 +102,11 @@
     display: contents;
 }
 
+.persistentContent,
+.inertContent {
+    display: contents;
+}
+
 .backdrop {
     position: fixed;
     inset: 0;

src/sidebar/sidebar.stories.tsx

@@ -1,8 +1,8 @@
 import * as React from 'react'
 
-import { Box, Button, Heading, Stack, Text } from '../index'
+import { Box, Button, Heading, IconButton, Stack, Text } from '../index'
 
-import { Sidebar, SidebarContent, SidebarResizeHandle } from './sidebar'
+import { Sidebar, SidebarContent, SidebarPersistentContent, SidebarResizeHandle } from './sidebar'
 
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import type { SidebarAlign, SidebarOverlayMode } from './sidebar'
@@ -102,8 +102,11 @@ const CARD_SKIN = {
 
 /**
  * Applies `inert` to the main element while a modal sidebar is open. This is the
- * consumer's job (the sidebar can't set attributes on a sibling); it is wired
- * imperatively here because this `@types/react` does not type the `inert` prop.
+ * consumer's job (the sidebar can't set attributes on a sibling). It is set
+ * imperatively rather than via an `inert` prop because Reactist supports React 18,
+ * where `@types/react` doesn't type `inert` and the runtime doesn't toggle it from a
+ * boolean; first-class `inert` support is React 19+.
+ * @see https://github.com/facebook/react/blob/main/CHANGELOG.md#1900-december-5-2024 — React 19.0.0: "Add support for `inert`" (#24730 by @eps1lon)
  */
 function useInert(active: boolean) {
     const ref = React.useRef<HTMLElement>(null)
@@ -221,6 +224,97 @@ export const Docked = {
     },
 } satisfies Story
 
+function SidebarToggleIcon() {
+    return (
+        <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+            <rect
+                x="1.75"
+                y="2.75"
+                width="12.5"
+                height="10.5"
+                rx="1.5"
+                stroke="currentColor"
+                strokeWidth="1.5"
+            />
+            <line x1="6" x2="6" y1="3" y2="13" stroke="currentColor" strokeWidth="1.5" />
+        </svg>
+    )
+}
+
+SidebarToggleIcon.displayName = 'SidebarToggleIcon'
+
+/**
+ * A docked main nav whose collapse toggle lives in `<SidebarPersistentContent>`, the
+ * pattern Todoist, Comms, and Automations share. The toggle rides the collapse
+ * animation and peeks at the freed edge while collapsed, staying reachable to reopen.
+ */
+export const CollapsibleNav = {
+    render: function CollapsibleNav() {
+        const [isOpen, setIsOpen] = React.useState(true)
+
+        const toggle = (
+            <IconButton
+                variant="secondary"
+                icon={<SidebarToggleIcon />}
+                aria-label={isOpen ? 'Collapse sidebar' : 'Open sidebar'}
+                aria-controls="collapsible-nav"
+                aria-expanded={isOpen}
+                onClick={() => setIsOpen((open) => !open)}
+            />
+        )
+
+        return (
+            <Box display="flex" height="full">
+                <Sidebar id="collapsible-nav" align="start" isOpen={isOpen} width={260}>
+                    <SidebarContent style={PANEL_SKIN}>
+                        <SidebarPersistentContent>
+                            {isOpen ? (
+                                <Box display="flex" justifyContent="flexEnd" padding="small">
+                                    {toggle}
+                                </Box>
+                            ) : (
+                                <div
+                                    style={{
+                                        position: 'absolute',
+                                        top: 8,
+                                        left: '100%',
+                                        zIndex: 2,
+                                    }}
+                                >
+                                    {toggle}
+                                </div>
+                            )}
+                        </SidebarPersistentContent>
+                        <Box as="nav" aria-label="Primary">
+                            <DemoNav />
+                        </Box>
+                    </SidebarContent>
+                </Sidebar>
+                <Box
+                    as="main"
+                    flexGrow={1}
+                    minWidth={0}
+                    paddingY="large"
+                    paddingRight="large"
+                    paddingLeft={isOpen ? 'large' : 'xxlarge'}
+                    overflow="auto"
+                >
+                    <Stack space="medium">
+                        <Heading level="2" size="larger">
+                            Main content
+                        </Heading>
+                        <Text tone="secondary">
+                            Collapse the nav with the toggle in its header. While collapsed the
+                            panel slides away and the toggle peeks at the edge, staying reachable to
+                            reopen.
+                        </Text>
+                    </Stack>
+                </Box>
+            </Box>
+        )
+    },
+} satisfies Story
+
 /**
  * Adding a `<SidebarResizeHandle>` makes the panel resizable: the handle sits on
  * the inner edge (right for `align="start"`), drives a render-free pointer drag,

src/sidebar/sidebar.test.tsx

@@ -4,7 +4,7 @@ import { act, fireEvent, render, screen, waitFor, within } from '@testing-librar
 import userEvent from '@testing-library/user-event'
 import { axe } from 'jest-axe'
 
-import { Sidebar, SidebarContent, SidebarResizeHandle } from './sidebar'
+import { Sidebar, SidebarContent, SidebarPersistentContent, SidebarResizeHandle } from './sidebar'
 
 import type { SidebarAlign, SidebarProps } from './sidebar'
 
@@ -292,6 +292,34 @@ describe('unmountOnHide', () => {
     })
 })
 
+describe('SidebarPersistentContent', () => {
+    it('renders in the panel and stays visible when open, and out of the inert when closed', async () => {
+        const { rerender } = renderSidebar(
+            {},
+            {
+                children: (
+                    <nav aria-label="Main navigation">
+                        <SidebarPersistentContent>
+                            <button type="button">Toggle sidebar</button>
+                        </SidebarPersistentContent>
+                        <a href="#projects">Projects</a>
+                    </nav>
+                ),
+            },
+        )
+
+        const panel = screen.getByTestId('sidebar-panel')
+        const toggle = await within(panel).findByRole('button', { name: 'Toggle sidebar' })
+        expect(toggle).toBeVisible()
+        expect(toggle.closest('[inert]')).toBeNull()
+        expect(screen.getByText('Projects').closest('[inert]')).toBeNull()
+
+        rerender({ isOpen: false })
+        expect(screen.getByText('Projects').closest('[inert]')).not.toBeNull()
+        expect(toggle.closest('[inert]')).toBeNull()
+    })
+})
+
 describe('resize', () => {
     const WIDTH = 280
     const MIN_WIDTH = 210

src/sidebar/sidebar.tsx

@@ -1,4 +1,5 @@
 import * as React from 'react'
+import { createPortal } from 'react-dom'
 import FocusLock from 'react-focus-lock'
 
 import { hideOthers } from 'aria-hidden'
@@ -43,6 +44,13 @@ type SidebarContextValue = {
 
 const SidebarContext = React.createContext<SidebarContextValue | null>(null)
 
+/**
+ * Scoped to `<SidebarContent>`: carries the live region that `<SidebarPersistentContent>`
+ * portals into. `undefined` (the default) means there is no enclosing `<SidebarContent>`;
+ * `null` means one is present but its region element has not attached yet.
+ */
+const SidebarContentContext = React.createContext<HTMLElement | null | undefined>(undefined)
+
 function useSidebarContext(componentName: string): SidebarContextValue {
     const context = React.useContext(SidebarContext)
     if (context === null) {
@@ -291,6 +299,8 @@ const SidebarContent = React.forwardRef<HTMLDivElement, SidebarContentProps>(
         } = useSidebarContext('SidebarContent')
 
         const mergedRef = useMergeRefs([panelRef, ref])
+        const inertContentRef = React.useRef<HTMLDivElement>(null)
+        const [persistentRegion, setPersistentRegion] = React.useState<HTMLElement | null>(null)
 
         const isDialog = overlayOpen && (overlayMode === 'dialog' || overlayMode === 'modal')
         const ariaModal = overlayOpen && overlayMode === 'modal' ? true : undefined
@@ -305,6 +315,14 @@ const SidebarContent = React.forwardRef<HTMLDivElement, SidebarContentProps>(
             [shouldTrap, panelRef],
         )
 
+        // `inert` is a prop only in React 19+; toggle it imperatively to support React 18.
+        React.useEffect(
+            function inertContentWhileClosed() {
+                inertContentRef.current?.toggleAttribute('inert', !isOpen)
+            },
+            [isOpen],
+        )
+
         const widthStyle =
             width != null
                 ? ({ [SIDEBAR_WIDTH_VAR]: `${width}px` } as React.CSSProperties)
@@ -352,7 +370,12 @@ const SidebarContent = React.forwardRef<HTMLDivElement, SidebarContentProps>(
                     className={styles.focusLock}
                     data-testid="sidebar-focus-lock"
                 >
-                    {childrenToRender}
+                    <div ref={setPersistentRegion} className={styles.persistentContent} />
+                    <SidebarContentContext.Provider value={persistentRegion}>
+                        <div ref={inertContentRef} className={styles.inertContent}>
+                            {childrenToRender}
+                        </div>
+                    </SidebarContentContext.Provider>
                 </FocusLock>
             </Box>
         )
@@ -532,6 +555,39 @@ function SidebarResizeHandle({
     )
 }
 
+//
+// SidebarPersistentContent
+//
+
+/**
+ * Renders its children inside the panel but outside the closed-state `inert`
+ * wrapper, so a control placed here (e.g. a collapse toggle) stays operable while
+ * the sidebar is closed, rides the collapse transition, and joins the focus trap
+ * when modal. Portals into a region `<SidebarContent>` provides, so it works at any
+ * depth within it; used outside a `<SidebarContent>` it warns and renders nothing.
+ * The consumer owns the control, its `aria-*`, and its positioning.
+ *
+ * @see Sidebar
+ * @see SidebarContent
+ */
+function SidebarPersistentContent({ children }: { children?: React.ReactNode }) {
+    const region = React.useContext(SidebarContentContext)
+
+    React.useEffect(
+        function warnWhenOutsideContent() {
+            if (region === undefined) {
+                // eslint-disable-next-line no-console
+                console.warn(
+                    '[Sidebar]: <SidebarPersistentContent> must be nested within <SidebarContent>; its children will not render.',
+                )
+            }
+        },
+        [region],
+    )
+
+    return region ? createPortal(children, region) : null
+}
+
 //
 // Backdrop (auto-rendered for modal overlays)
 //
@@ -564,7 +620,7 @@ function SidebarBackdrop() {
 
 SidebarContent.displayName = 'SidebarContent'
 
-export { Sidebar, SidebarContent, SidebarResizeHandle, useSidebar }
+export { Sidebar, SidebarContent, SidebarPersistentContent, SidebarResizeHandle, useSidebar }
 export type {
     SidebarAlign,
     SidebarContentProps,