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

<Meta of={SectionHeaderStories} />

# SectionHeader

The 32px row a section starts with: a SectionLabel, and actions that
appear while the row is hovered or keyboard-focused, as IconButtons with
tooltips — always, on a screen with no hover. It is also the
header of a **CollapsibleSection**, which draws the chevron and makes the
title the toggle — that is where a section folds.

<Canvas of={SectionHeaderStories.WithActions} />

## When

- A sidebar or panel section that carries its own actions — add, sort,
  filter.
- **A heading over a group of rows, even with nothing to act on**: no
  `actions`, and `hover="none"` so the row stays still under the pointer.
  Never a row drawn by hand with a SectionLabel in it.
- `showActions="always"` keeps the actions visible — for touch, or for a
  section whose actions are the point.

<Canvas of={SectionHeaderStories.PersistentActions} />

- `menu` gives the section a "More options" ⋮ after its actions, with what
  acts on the whole section — a folder's Rename, Archive. It is **NavItem**'s
  ⋮, revealed with the actions, and stays while its menu is open.

<Canvas of={SectionHeaderStories.WithMenu} />

- `look="quiet"`: a small grey label over a list whose rows are rows, not
  headings — "Folders" over the folders — with its action held on screen.
  It never lights up under the pointer; its button does.

<Canvas of={SectionHeaderStories.Quiet} />

- `look="row"`: the header is a row among rows — a folder in a sidebar. Use
  it through **CollapsibleSection**'s `look="row"`.

## When not

- A section that opens and closes → **CollapsibleSection**: the header,
  the rows, the slide, and a `storageKey` that remembers.
- A label inside a row of another shape — a dialog's section, a panel's
  title, a card's line → **SectionLabel**.
- A heading inside a menu → **MenuSection**.
- Page-level headings → the `h*` type tokens.

## How

```tsx
import { SectionHeader } from '@estiva-app/ui'
import { IconPlus } from '@tabler/icons-react'

<SectionHeader title="Sections" actions={[{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: add }]} />
```

- `chevron`, `isExpanded` and `onToggle` are CollapsibleSection's to set
  (one component folds, and it is that one). With
  them, the title is a button that fills the row up to the actions — the
  whole row is the hit target, the keyboard can toggle it, and it says its
  state (`aria-expanded`).
- An action is `{ icon, tooltip, onClick }` — the tooltip doubles as the
  action's accessible name. The actions sit beside the title button, not
  inside it, so a click on one never also toggles the section.
- `count` is how many there are, 8px after the title, in a tab's count
  style: a heading over a list says its number beside its name.
- `trailing` sits at the row's end, before the actions, and stays on screen
  while they come and go: a chip, or an unread dot. It is outside the title
  button, so it is neither part of the toggle's name nor part of its hit
  target.
- `render` swaps the title's element in Base UI's manner; it is how
  CollapsibleSection makes the title a `Collapsible.Trigger`.

- `hover="none"` keeps the row still under the pointer: for a heading whose
  actions are always shown (`showActions="always"`), where the buttons light up
  on their own. The default, `fill`, lights a row that toggles or has actions.

- The row is 32px tall, 8px in on each side, 4px between the title and the
  actions, with 8px corners.

## 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 |
|---|---|---|
| With `chevron`, its title is a button that calls `onToggle` on a click, Enter or Space, and says whether it is open | a button of your own, or `aria-expanded` |  |
| Shows its actions while the keyboard is in the row — on the title or on one of them — and always on a screen with no hover | a focus style of your own |  |
| Keeps its 32px in a scrolling column | `shrink-0` |  |

## Keys

| Key | Does |
|---|---|
| Enter, Space | on the title, with `chevron`: calls `onToggle` |
| Tab | the title, then each action — the actions show from the title on |

## Props

<Controls of={SectionHeaderStories.Plain} />