import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
import * as SidebarStories from './Sidebar.stories'

<Meta of={SidebarStories} />

# Sidebar

The navigation column: 240px, a hairline on its right, the surface behind
it, scrolling independently of the content beside it. What goes inside is
the caller's — this is the shell.

<Canvas of={SidebarStories.Composed} />

## When

- The structured frame's navigation (AppShell's `solid` variant), filled
  with **NavItem** rows — the sidebar pairs with the solid TopBar, as the
  Rail pairs with the floating one.
- A labelled group inside it, of two kinds (the Composed story shows
  both): one the reader can fold away and that stays how they left it —
  a **CollapsibleSection** — and one that stays open, a **SectionHeader**
  over its rows.
- It scrolls on its own — a long list never scrolls the frame away.

<Canvas of={SidebarStories.Scrolls} />

## When not

- An icon strip → **Rail**.
- Sections within a page's content → **SectionHeader** over content, not
  a second sidebar.
- Desktop only — there is no narrow-screen drawer; don't improvise one
  per app.

## How

```tsx
import { Sidebar, NavItem, CollapsibleSection, SectionHeader } from '@estiva-app/ui'

<Sidebar>
  <NavItem href="/documents" label="Documents" active />
  <CollapsibleSection title="Collections" storageKey="app.sidebar.collections" className="mt-2 shrink-0" contentClassName="gap-px">
    <NavItem href="/collections/12" label="Quarterly plan" count={7} countLabel="7 open" />
  </CollapsibleSection>
  <SectionHeader title="Pinned" className="mt-2 shrink-0" />
  <NavItem href="/documents/3" label="Reading list" />
</Sidebar>
```

**Every row is a plain anchor, so in a router app each click would reload
the page** — unless the app gives **AppProvider**'s `navigate`, which
changes page in place. See **NavItem**.

Anything you place directly in the column needs `shrink-0` (both headings
above take it in `className`):
the column scrolls on overflow, and a flex child without it gets
compressed instead — rows must keep their height.

It is a `nav` region — pass `aria-label` when "Workspace" is not the
right name for what it navigates.

## What it owns

It does these by itself. Write none of them around it.

| It does | So you never write | Refused when written by hand |
|---|---|---|
| Scrolls its rows in a ScrollArea when they overflow | `overflow-auto` on the column |  |

## Props

<Controls of={SidebarStories.Composed} />