@d4gger/design-system 2.7.0 → 3.0.1

package/dist/docs/sidebar-guide.md

@@ -1,732 +0,0 @@
-# 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>
-```