@d4gger/design-system 2.7.0

package/dist/docs/sidebar-guide.md

@@ -0,0 +1,732 @@
+# Sidebar Guide
+
+A usage and accessibility reference for the `Sidebar` composite. The canonical
+anatomy, props, and token map live in [`sidebar.md`](./sidebar.md); this guide
+walks through how to assemble, style, and ship the composite in real product
+shells.
+
+`Sidebar` is a panel and cabinet shell. It owns the expanded / collapsed state,
+the persistence backend, the global toggle shortcut, the mobile sheet fallback,
+and the `data-state` / `data-collapsed` / `data-active` attribute contract. The
+app owns the route map, the auth and permissions policy, the nav registry, and
+the persistence target.
+
+## Quick Start
+
+A minimal working shell has a `Sidebar.Provider`, a `Sidebar` panel, and a
+`Sidebar.Inset` for the main content. The provider holds the expanded state, the
+panel renders the navigation, and the inset fills the rest of the row.
+
+```tsx
+import { Sidebar } from '@d4gger/design-system'
+
+export function AppShell({ children }: { children: React.ReactNode }) {
+  return (
+    <Sidebar.Provider defaultExpanded storageKey="app-sidebar">
+      <Sidebar>
+        <Sidebar.Header>
+          <span data-persistent="true">Acme</span>
+        </Sidebar.Header>
+
+        <Sidebar.Content>
+          <Sidebar.Menu>
+            <Sidebar.MenuItem>
+              <Sidebar.MenuButton isActive asChild>
+                <a href="/dashboard">
+                  <HomeIcon />
+                  Dashboard
+                </a>
+              </Sidebar.MenuButton>
+            </Sidebar.MenuItem>
+            <Sidebar.MenuItem>
+              <Sidebar.MenuButton asChild>
+                <a href="/settings">
+                  <SettingsIcon />
+                  Settings
+                </a>
+              </Sidebar.MenuButton>
+            </Sidebar.MenuItem>
+          </Sidebar.Menu>
+        </Sidebar.Content>
+
+        <Sidebar.Footer>
+          <span data-persistent="true">v1.0.0</span>
+        </Sidebar.Footer>
+
+        <Sidebar.Rail />
+      </Sidebar>
+
+      <Sidebar.Inset>{children}</Sidebar.Inset>
+    </Sidebar.Provider>
+  )
+}
+```
+
+The panel renders as a `<nav>` element with `aria-label="Sidebar"`. Every
+provider, root, and slot writes `data-state` (`expanded` | `collapsed`) and
+`data-collapsed` (`true` | `false`). The `data-persistent="true"` children in
+the header and footer stay visible when the panel collapses.
+
+The `useSidebar` hook returns the context value, or a no-op fallback when a slot
+is rendered outside a `Sidebar.Provider`. Read or set `expanded`, peek at
+`isMobile`, or grab `sidebarId` for `aria-controls` wiring.
+
+```tsx
+import { useSidebar } from '@d4gger/design-system'
+
+function CollapseButton() {
+  const { expanded, setExpanded } = useSidebar()
+  return (
+    <button onClick={() => setExpanded((v) => !v)}>
+      {expanded ? 'Collapse' : 'Expand'}
+    </button>
+  )
+}
+```
+
+## Collapsible Modes
+
+`Sidebar.Provider` accepts a `collapsible` prop with three values. The mode
+sets the panel's interaction model and writes `data-collapsible` to the
+provider, the root, and every slot that reads from `useSidebar()`.
+
+### `offcanvas` (default)
+
+The panel slides between full width and zero width but remains mounted so
+local component state is preserved. When collapsed it is `inert`,
+`aria-hidden`, and pointer-inactive. A provider-owned recovery rail stays
+outside the panel.
+
+```tsx
+<Sidebar.Provider collapsible="offcanvas" defaultExpanded>
+  <Sidebar>
+    {/* ... */}
+  </Sidebar>
+  <Sidebar.Inset>{children}</Sidebar.Inset>
+</Sidebar.Provider>
+```
+
+In `offcanvas` mode, a consumer `Sidebar.Rail` collapses the expanded panel.
+The provider-owned `data-slot="sidebar-recovery-rail"` button reopens the
+zero-width panel.
+
+### `icon`
+
+The panel collapses to an icon rail and re-expands on hover (desktop only,
+fine pointer). Use this when the panel should stay visible at all times but
+the screen real estate is tight. The `Sidebar.Trigger` and the `Sidebar.Rail`
+both render. Collapsed `Sidebar.MenuButton` instances auto-wrap their text
+label in a tooltip.
+
+```tsx
+<Sidebar.Provider collapsible="icon" defaultExpanded>
+  <Sidebar>
+    {/* ... */}
+    <Sidebar.Rail />
+  </Sidebar>
+  <Sidebar.Inset>{children}</Sidebar.Inset>
+</Sidebar.Provider>
+```
+
+In `icon` mode, the rail uses the `dsx-sidebar__rail--edge` modifier and renders
+as a 4px hover-detected edge instead of the chevron button. The collapsed width
+follows `var(--dsx-size-2xl, 48px)`.
+
+### `none`
+
+The panel never collapses. The `Sidebar.Rail` and the `Sidebar.Trigger` return
+`null`. The `Ctrl+B` / `Cmd+B` shortcut is a no-op. Use this when the panel
+should always be full width, for example in a help center or settings area
+where collapsing would hide the IA.
+
+```tsx
+<Sidebar.Provider collapsible="none" defaultExpanded>
+  <Sidebar>
+    {/* ... */}
+  </Sidebar>
+  <Sidebar.Inset>{children}</Sidebar.Inset>
+</Sidebar.Provider>
+```
+
+The CSS rule `.dsx-sidebar[data-collapsible='none']` pins the panel to
+`var(--dsx-sidebar-width)` and hides the rail and trigger as a safety net.
+
+### Mode comparison
+
+| Mode | Collapsed width | Rail | Trigger | Tooltip on collapsed buttons | Hover-to-expand |
+| --- | --- | --- | --- | --- | --- |
+| `offcanvas` | `0` (mounted) | provider recovery rail | yes | no | no |
+| `icon` | `var(--dsx-size-2xl, 48px)` | edge | yes | yes | yes (desktop) |
+| `none` | n/a (always expanded) | hidden | hidden | n/a | n/a |
+
+## Submenus
+
+Nested navigation uses `Sidebar.MenuSub`, `Sidebar.MenuSubItem`, and
+`Sidebar.MenuSubButton`. The sub is a `<ul>`, the sub item is a `<li>`, and
+the sub button is a `<button>` with the same prop set as `Sidebar.MenuButton`.
+
+```tsx
+<Sidebar.MenuItem>
+  <Sidebar.MenuButton asChild>
+    <a href="/billing">
+      <CreditCardIcon />
+      Billing
+    </a>
+  </Sidebar.MenuButton>
+
+  <Sidebar.MenuSub>
+    <Sidebar.MenuSubItem>
+      <Sidebar.MenuSubButton isActive asChild>
+        <a href="/billing/invoices">Invoices</a>
+      </Sidebar.MenuSubButton>
+    </Sidebar.MenuSubItem>
+    <Sidebar.MenuSubItem>
+      <Sidebar.MenuSubButton asChild>
+        <a href="/billing/subscriptions">Subscriptions</a>
+      </Sidebar.MenuSubButton>
+    </Sidebar.MenuSubItem>
+  </Sidebar.MenuSub>
+</Sidebar.MenuItem>
+```
+
+### Keyboard navigation
+
+`Sidebar.Menu` and `Sidebar.MenuSub` both bind a `keydown` handler. The
+handler runs `handleMenuKeyboardNav`, which moves focus through the matching
+button selector (`.dsx-sidebar__menu-button, .dsx-sidebar__menu-sub-button`
+for menus, `.dsx-sidebar__menu-sub-button` for submenus) using a roving
+`tabIndex` pattern.
+
+| Key | Action |
+| --- | --- |
+| `ArrowDown` | Move focus to the next button. Wraps to the first. |
+| `ArrowUp` | Move focus to the previous button. Wraps to the last. |
+| `Home` | Move focus to the first button. |
+| `End` | Move focus to the last button. |
+| `Escape` (submenu) | Return focus to the parent `MenuButton`. |
+
+The submenu's `Escape` handler walks up to the closest `.dsx-sidebar__menu-item`,
+finds the first `.dsx-sidebar__menu-button`, and focuses it. The handler calls
+`e.preventDefault()` and `e.stopPropagation()` so the mobile sheet does not
+also close.
+
+### Accessibility
+
+`Sidebar.MenuSubButton` writes `aria-current="page"` when `isActive` is set,
+matching the behavior of `Sidebar.MenuButton`. The `data-active="true"`
+attribute and the `dsx-sidebar-menu-button-active` class are also applied, so
+the visual state and the screen-reader state stay in sync.
+
+If you need a custom trigger on the submenu (a chevron, an open / close toggle),
+stack a `Sidebar.MenuAction` next to the `Sidebar.MenuButton` inside the
+`Sidebar.MenuItem`. The action reveals on hover and `focus-within`.
+
+## Mobile
+
+The provider mounts a mobile sheet fallback when `mobile !== 'none'` and
+`isMobile` is true. `isMobile` resolves to `window.innerWidth < mobileBreakpoint`
+or `window.matchMedia('(pointer: coarse)').matches`. The default
+`mobileBreakpoint` is `768`.
+
+```tsx
+<Sidebar.Provider
+  mobile="sheet"
+  mobileBreakpoint={768}
+  defaultExpanded
+>
+  {/* ... */}
+</Sidebar.Provider>
+```
+
+When the device is mobile, the provider lazy-loads `Sheet`, `SheetTrigger`,
+and `SheetContent`, and mounts a `<button aria-label="Open sidebar"
+class="dsx-sidebar__mobile-trigger">` in the top-left of the shell. The
+button opens a `Sheet` with `side="left"` and `showClose`, and the children
+render inside the `Sheet.Content` instead of inline.
+
+Trigger behavior:
+
+- **Mobile (`isMobile === true`):** the `Sheet` trigger mounts, the inline
+  panel is replaced by the sheet surface. The mobile trigger owns opening
+  and closing the sheet; `Ctrl+B` / `Cmd+B` only updates the persisted
+  desktop expansion preference.
+- **Desktop (`isMobile === false`):** the inline panel renders normally. The
+  mobile trigger does not mount.
+
+Pass `mobile="none"` to skip the fallback entirely. Use this when the app
+owns its own mobile shell.
+
+When the viewport crosses the breakpoint, the provider debounces the resize
+handler by 100 ms and updates `isMobile`. The mobile sheet closes
+automatically when the user resizes back to a desktop width.
+
+## Accessibility
+
+The composite writes the ARIA contract for you. You should not duplicate it
+with wrapper elements. Here's the surface that ships out of the box.
+
+### Landmark
+
+The panel is a `<nav aria-label="Sidebar">` element. The `Sidebar.Inset` is a
+`<main>` element by default, or a `Slot` child when `asChild` is set. Screen
+readers announce the panel as a navigation region. Override the `aria-label`
+when the panel needs product-specific copy:
+
+```tsx
+<Sidebar aria-label="Primary">...</Sidebar>
+```
+
+### Toggle state
+
+`Sidebar.Rail` and `Sidebar.Trigger` both write `aria-expanded` and
+`aria-controls` against the panel's `sidebarId`. The provider generates
+`sidebarId` from `React.useId()`. The `aria-label` flips between
+`Expand sidebar` and `Collapse sidebar` based on the current state. Override
+with `collapsedLabel` and `expandedLabel` on the trigger:
+
+```tsx
+<Sidebar.Trigger
+  collapsedLabel="Open navigation"
+  expandedLabel="Close navigation"
+/>
+```
+
+The rail writes `aria-expanded` even in `icon` mode. It sets `tabIndex={-1}`
+in `icon` mode so the rail is skipped during tab navigation; the chevron is
+decorative there, and the hover affordance is the interaction.
+
+### Active page
+
+`Sidebar.MenuButton` and `Sidebar.MenuSubButton` write `aria-current="page"`
+when `isActive` is set. The visual state and the announced state stay
+aligned. Use `asChild` with a router `Link` to make the active item a
+navigable link rather than a button:
+
+```tsx
+<Sidebar.MenuButton isActive asChild>
+  <Link href="/dashboard">Dashboard</Link>
+</Sidebar.MenuButton>
+```
+
+The `asChild` prop swaps the host for a `Slot`, so the `aria-current`,
+`data-active`, and `dsx-sidebar-menu-button-active` class all flow to the
+`Link` element.
+
+### Skip link
+
+`Sidebar.SkipLink` renders an anchor that visually hides itself until it
+receives focus, then anchors to the element with the matching `id`. Place it
+once at the top of the shell. The default `targetId` is `main`, which matches
+the `Sidebar.Inset` host by default; pass a different id when the inset is
+composed with a custom `asChild` host.
+
+```tsx
+<Sidebar.SkipLink targetId="main" />
+```
+
+The link uses `position: absolute; top: -100%` and slides into view on
+`:focus`. The skip link inherits the focus ring from
+`var(--dsx-shadow-focus-ring)`.
+
+### Keyboard shortcut
+
+`Ctrl+B` (Windows and Linux) and `Cmd+B` (macOS) toggle the panel when
+`Sidebar.Provider` mounts and `toggleShortcut={true}`. The shortcut is
+global, so it fires from anywhere on the page. The handler calls
+`event.preventDefault()` and is a no-op when `collapsible="none"`.
+
+Pass `toggleShortcut={false}` to disable the global listener. Useful for
+embedded surfaces where the host app already owns `Ctrl+B`.
+
+### Reduced motion
+
+The CSS file gates the panel width transition and the menu action opacity
+transition behind `var(--dsx-motion-duration-*)` tokens, and a
+`@media (prefers-reduced-motion: reduce)` rule zeros them out:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .dsx-sidebar,
+  .dsx-sidebar__menu-action {
+    transition: none;
+  }
+}
+```
+
+The source also reads `window.matchMedia('(prefers-reduced-motion: reduce)')`
+in `SidebarRoot` to short-circuit hover timers and perform focus transfer
+immediately.
+
+### Focus management
+
+On collapse, focus moves to the provider-owned recovery rail after the width
+transition. On expansion, focus moves to a registered `Sidebar.Trigger`, or
+to the sidebar root when no trigger is registered. Under reduced motion both
+transfers happen immediately.
+
+The auto-scroll on the active `MenuButton` also respects reduced motion. The
+`useAutoScroll` hook calls `el.scrollIntoView({ block: 'nearest', behavior:
+prefersReducedMotion ? 'auto' : 'smooth' })`.
+
+## Advanced
+
+### Hover-to-expand (icon mode, desktop only)
+
+In `collapsible="icon"`, the panel auto-expands on mouse enter and collapses
+on mouse leave when the device has a fine pointer and hover capability. The
+source checks `window.matchMedia('(hover: hover) and (pointer: fine)')`. The
+hover timer fires after 100 ms on enter and 120 ms on leave. Under
+`prefers-reduced-motion`, the timer is skipped.
+
+The auto-expand and auto-collapse use two refs to coordinate with manual
+toggles:
+
+- `manualToggleRef.current = true` after a click on the rail or trigger. The
+  panel stays in the user-chosen state until the next click.
+- `autoExpandedRef.current = true` while the auto-expand is active. The
+  hover-leave handler only collapses when `autoExpandedRef.current` is true
+  and `manualToggleRef.current` is false, so a user click during a hover
+  doesn't snap back.
+
+### Tooltip on collapsed items
+
+In `icon` mode, `Sidebar.MenuButton` and `Sidebar.MenuSubButton` wrap their
+text children in a `Tooltip` when the panel is collapsed. The tooltip
+extracts the label from string and number children, and renders on the
+right side:
+
+```tsx
+// In icon mode, collapsed:
+<Sidebar.MenuButton>
+  <SettingsIcon />
+  Settings
+</Sidebar.MenuButton>
+// Renders: <Tooltip><TooltipTrigger asChild><button>...</button></TooltipTrigger>
+//          <TooltipContent side="right">Settings</TooltipContent></Tooltip>
+```
+
+The `showTooltip` gate is `collapsible === 'icon' && !expanded && !isMobile
+&& label !== ''`. When `asChild` is set, the tooltip does not render, since
+the host is the consumer's element.
+
+### Nested sidebar (two-tier layout)
+
+Pass `nested` to a `Sidebar.Provider` that's rendered inside another
+`Sidebar.Provider` shell. The provider exposes a `SidebarNestedContext` with
+a counter ref and an `isActive` flag. The inner `Sidebar` registers itself on
+mount and unmount. When the counter goes above 1, the inner `Sidebar` flips
+into a nested instance: it forces `collapsible="none"`, writes
+`data-nested="true"`, drops the rail and trigger, and the CSS rule
+`.dsx-sidebar[data-nested='true']` paints a left border to signal the
+hierarchy.
+
+```tsx
+function OuterShell() {
+  return (
+    <Sidebar.Provider defaultExpanded>
+      <Sidebar>
+        <Sidebar.Content>
+          <Sidebar.Menu>
+            <Sidebar.MenuItem>
+              <Sidebar.MenuButton isActive asChild>
+                <a href="/admin">Admin</a>
+              </Sidebar.MenuButton>
+            </Sidebar.MenuItem>
+          </Sidebar.Menu>
+        </Sidebar.Content>
+        <Sidebar.Rail />
+      </Sidebar>
+
+      <Sidebar.Inset>
+        <AdminDetail />
+      </Sidebar.Inset>
+    </Sidebar.Provider>
+  )
+}
+
+function AdminDetail() {
+  return (
+    <Sidebar.Provider nested defaultExpanded>
+      <Sidebar>
+        <Sidebar.Content>
+          <Sidebar.Menu>
+            <Sidebar.MenuItem>
+              <Sidebar.MenuButton isActive asChild>
+                <a href="/admin/users">Users</a>
+              </Sidebar.MenuButton>
+            </Sidebar.MenuItem>
+            <Sidebar.MenuItem>
+              <Sidebar.MenuButton asChild>
+                <a href="/admin/audit">Audit</a>
+              </Sidebar.MenuButton>
+            </Sidebar.MenuItem>
+          </Sidebar.Menu>
+        </Sidebar.Content>
+      </Sidebar>
+
+      <Sidebar.Inset>...</Sidebar.Inset>
+    </Sidebar.Provider>
+  )
+}
+```
+
+The outer provider owns the persisted state. The inner provider's persisted
+state uses an in-memory backend (`storageKey: undefined`), so the inner
+collapse state does not leak across reloads.
+
+### Edge rail
+
+In `icon` mode, the `Sidebar.Rail` switches to a 4px hover-detected edge
+that runs the full height of the panel. The edge is invisible at rest,
+paints a 2px `var(--dsx-color-primary)` strip on hover, and reveals itself
+with an inset focus ring on `:focus-visible`. The rail is `tabIndex={-1}` in
+icon mode; the user toggles the panel by clicking the edge or by hovering
+the panel itself.
+
+### Custom styling via data attributes
+
+The composite writes a stable set of `data-*` attributes you can hook
+without adding wrapper classes. Every slot that reads from `useSidebar()`
+mirrors the provider's state through `getSidebarDataAttributes`.
+
+| Attribute | Values | Where | Use it for |
+| --- | --- | --- | --- |
+| `data-state` | `expanded`, `collapsed` | Provider, root, every slot | Primary visual state hook. |
+| `data-collapsed` | `true`, `false` | Same as `data-state` | Explicit boolean semantics for CSS. |
+| `data-collapsible` | `offcanvas`, `icon`, `none` | Provider, root, every slot | Mode-specific overrides. |
+| `data-active` | `true` (only when `isActive`) | `MenuButton`, `MenuSubButton` | Active row styling. |
+| `data-slot` | `sidebar-*` | Every slot | Targeted CSS hooks. |
+| `data-persistent` | `true` | Header / footer children | Children that stay visible when collapsed. |
+| `data-nested` | `true` | Root, in a nested provider | Inner shell styling. |
+| `data-slot` | `sidebar-recovery-rail` | Provider recovery button | Outside the zero-width offcanvas panel; owns `aria-controls` and `aria-expanded`. |
+| `data-show-icon` | `true`, `false` | `MenuSkeleton` | Skeleton icon visibility. |
+
+Common overrides:
+
+```css
+/* Tint the active row by your brand accent */
+.dsx-sidebar__menu-button[data-active='true'] {
+  background-color: var(--dsx-color-primary-container);
+}
+
+/* Pad the panel wider in offcanvas mode */
+.dsx-sidebar[data-collapsible='offcanvas'] {
+  --dsx-sidebar-width: 18rem;
+}
+
+/* Hide the version label in the footer when collapsed */
+.dsx-sidebar[data-state='collapsed'] .dsx-sidebar__footer [data-persistent='true'] {
+  display: none;
+}
+```
+
+## Composition Patterns
+
+### Header with logo and trigger
+
+The header is a flex row with `justify-content: space-between`. Drop a logo
+or product name on the left and the trigger on the right. Mark the logo
+`data-persistent="true"` so it stays visible when the panel collapses, and
+let the trigger slide away.
+
+```tsx
+<Sidebar.Header>
+  <Box data-persistent="true" display="flex" alignItems="center" gap="sm">
+    <Logo />
+    <strong>Acme</strong>
+  </Box>
+  <Sidebar.Trigger />
+</Sidebar.Header>
+```
+
+The CSS rule `.dsx-sidebar[data-state='collapsed']
+.dsx-sidebar__header > :not(.dsx-sidebar__trigger):not([data-persistent='true'])
+{ display: none }` hides non-trigger, non-persistent children when the panel
+collapses.
+
+### Footer with user profile
+
+The footer mirrors the header. Put the avatar and user name on the left and
+a settings shortcut on the right. The same `data-persistent` rule applies.
+
+```tsx
+<Sidebar.Footer>
+  <Box data-persistent="true" display="flex" alignItems="center" gap="sm">
+    <Avatar src={user.avatar} size="sm" />
+    <Box>
+      <Text size="sm" weight="medium">{user.name}</Text>
+      <Text size="xs" color="on-surface-variant">{user.email}</Text>
+    </Box>
+  </Box>
+  <Sidebar.MenuAction aria-label="Account settings">
+    <SettingsIcon />
+  </Sidebar.MenuAction>
+</Sidebar.Footer>
+```
+
+### Grouped navigation sections
+
+`Sidebar.Group` is a vertical cluster with optional `GroupLabel`,
+`GroupContent`, and `GroupAction`. Use `GroupLabel` for the section heading
+and `GroupContent` for the menu body. `GroupAction` slots an action button
+at the end of the row (a "See all" link, for example).
+
+```tsx
+<Sidebar.Content>
+  <Sidebar.Group>
+    <Sidebar.GroupLabel>Workspace</Sidebar.GroupLabel>
+    <Sidebar.GroupContent>
+      <Sidebar.Menu>
+        <Sidebar.MenuItem>
+          <Sidebar.MenuButton isActive asChild>
+            <a href="/projects">Projects</a>
+          </Sidebar.MenuButton>
+        </Sidebar.MenuItem>
+        <Sidebar.MenuItem>
+          <Sidebar.MenuButton asChild>
+            <a href="/teams">Teams</a>
+          </Sidebar.MenuButton>
+        </Sidebar.MenuItem>
+      </Sidebar.Menu>
+    </Sidebar.GroupContent>
+    <Sidebar.GroupAction asChild>
+      <a href="/workspace/new">+</a>
+    </Sidebar.GroupAction>
+  </Sidebar.Group>
+
+  <Sidebar.Separator />
+
+  <Sidebar.Group>
+    <Sidebar.GroupLabel>Account</Sidebar.GroupLabel>
+    <Sidebar.GroupContent>
+      <Sidebar.Menu>
+        <Sidebar.MenuItem>
+          <Sidebar.MenuButton asChild>
+            <a href="/profile">Profile</a>
+          </Sidebar.MenuButton>
+        </Sidebar.MenuItem>
+        <Sidebar.MenuItem>
+          <Sidebar.MenuButton asChild>
+            <a href="/billing">Billing</a>
+          </Sidebar.MenuButton>
+          <Sidebar.MenuBadge>3</Sidebar.MenuBadge>
+        </Sidebar.MenuItem>
+      </Sidebar.Menu>
+    </Sidebar.GroupContent>
+  </Sidebar.Group>
+</Sidebar.Content>
+```
+
+`Sidebar.Separator` is a `<div role="separator" aria-orientation="horizontal">`
+and renders the `dsx-separator dsx-separator--decorative` classes. Use it
+between groups, not inside them.
+
+### Loading state with skeletons
+
+`Sidebar.MenuSkeleton` renders a row-shaped loading placeholder with an
+optional icon circle. Use it while the nav data is hydrating.
+
+```tsx
+<Sidebar.Menu>
+  {isLoading
+    ? Array.from({ length: 4 }).map((_, i) => (
+        <Sidebar.MenuItem key={i}>
+          <Sidebar.MenuSkeleton showIcon />
+        </Sidebar.MenuItem>
+      ))
+    : items.map((item) => (
+        <Sidebar.MenuItem key={item.href}>
+          <Sidebar.MenuButton isActive={item.isActive} asChild>
+            <a href={item.href}>{item.label}</a>
+          </Sidebar.MenuButton>
+        </Sidebar.MenuItem>
+      ))}
+</Sidebar.Menu>
+```
+
+The skeleton writes `data-show-icon="true"` or `false` so the CSS can
+suppress the icon placeholder when `showIcon={false}`.
+
+### Active state styling
+
+The active menu button is communicated by:
+
+- `data-active="true"` on the button
+- `dsx-sidebar-menu-button-active` class
+- `aria-current="page"` for screen readers
+- Background `var(--dsx-effect-hover-primary)`
+- Text color `var(--dsx-color-primary)`
+- Inset 3px `var(--dsx-color-primary)` accent shadow
+
+You don't need to add any custom CSS for the default active state. If your
+product needs a different active treatment, override the class:
+
+```css
+.dsx-sidebar__menu-button[data-active='true'] {
+  background-color: var(--dsx-color-primary);
+  color: var(--dsx-color-on-primary);
+  box-shadow: none;
+}
+```
+
+## All Slots
+
+The composite exports 22 named subcomponents plus the `useSidebar` hook and
+the `Sidebar.SkipLink` accessibility helper. The list mirrors the source
+exports.
+
+| Slot | Element | Role |
+| --- | --- | --- |
+| `Sidebar.Provider` | `<div>` | State, persistence, shortcut, mobile fallback. |
+| `Sidebar` (alias `Sidebar.Root`) | `<nav>` | The panel. |
+| `Sidebar.Inset` | `<main>` | Main content area. |
+| `Sidebar.Rail` | `<button>` | Edge toggle. |
+| `Sidebar.Header` | `<div>` | Top region. |
+| `Sidebar.Content` | `<div>` (ScrollArea) | Scrollable middle. |
+| `Sidebar.Footer` | `<div>` | Bottom region. |
+| `Sidebar.Group` | `<div>` | Labelled cluster. |
+| `Sidebar.GroupLabel` | `<div>` | Section heading. |
+| `Sidebar.GroupAction` | `<button>` | Section row action. |
+| `Sidebar.GroupContent` | `<div>` | Group menu body. |
+| `Sidebar.Menu` | `<ul>` | List of menu items. |
+| `Sidebar.MenuItem` | `<li>` | A single row. |
+| `Sidebar.MenuBadge` | `<span>` | Count or status badge. |
+| `Sidebar.MenuAction` | `<button>` | Reveal-on-hover action. |
+| `Sidebar.MenuButton` | `<button>` | Menu button. |
+| `Sidebar.MenuSkeleton` | `<div>` | Loading placeholder. |
+| `Sidebar.MenuSub` | `<ul>` | Nested menu list. |
+| `Sidebar.MenuSubItem` | `<li>` | Nested menu row. |
+| `Sidebar.MenuSubButton` | `<button>` | Nested menu button. |
+| `Sidebar.Separator` | `<div>` | Horizontal divider. |
+| `Sidebar.Trigger` | `<button>` | Inline toggle. |
+| `Sidebar.SkipLink` | `<a>` | Accessibility skip link. |
+
+`useSidebar` returns the context value or a no-op fallback when a slot is
+rendered outside a provider. Always use the hook rather than importing the
+context directly, so your components degrade gracefully.
+
+```tsx
+import { useSidebar, type SidebarProviderProps } from '@d4gger/design-system'
+```
+
+## Persistence
+
+The provider reads and writes the expanded state to one of three backends.
+
+| `storage` value | Backend | Hydration-safe |
+| --- | --- | --- |
+| `localStorage` (default) | `window.localStorage` | yes |
+| `cookie` | `document.cookie` (SameSite=Lax, Path=/) | yes |
+| `memory` | React state only | n/a |
+
+The initial read runs in `useLayoutEffect` to avoid a flash of expanded
+content. The write runs in `useEffect`. The `memory` backend skips both.
+The default `storageKey` is `dsx-sidebar-state`. Override per provider when
+the app needs multiple shells with independent state:
+
+```tsx
+<Sidebar.Provider storageKey="cabinet-sidebar" defaultExpanded>
+  <Sidebar>...</Sidebar>
+  <Sidebar.Inset>{children}</Sidebar.Inset>
+</Sidebar.Provider>
+```