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

<Meta of={SectionLabelStories} />

# SectionLabel

**The** section-title span. Every section heading — sidebar sections, menu
headings, panel titles — renders through it, so a change of voice is one
edit. 12px / 500, primary text; some themes restyle it (the toolbar shows
how).

<Canvas of={SectionLabelStories.HeadingAList} />

## When

- **It is a bare label**: the row it sits in, and the room around it, are yours.
- A label inside a row of another shape: a dialog's section, a panel's
  title, a card's line.
- Inside a menu it arrives via **MenuSection** — don't place it there by
  hand.

## When not

- A heading over a group of rows → **SectionHeader**, even with nothing to
  act on; a group that folds → **CollapsibleSection**.
- The label above a stacked control → **Property** `stacked` — a field
  label is a different voice, at a different size, on purpose.
- Page-level headings → the `h*` type tokens.

## How

```tsx
import { SectionLabel } from '@estiva-app/ui'

<SectionLabel>Pinned</SectionLabel>
```

It is a bare span: the caller owns the row it sits in and the spacing
around it. Read it `tone="secondary"` where it labels rather than leads — menu
headings and the command palette's groups do. `tone="muted"` where it marks a
place in a list rather than heading it — a date between messages. `truncate`
cuts a long label short with an ellipsis where its row has no room. `folds`
is the title of a group that opens and closes: **SectionHeader** passes it
whenever it draws the chevron, so in Leaf a folding group keeps Ship's type
while every other label takes Signal's. A colour
passed in `className` is refused by the lint.

- Import it — never copy its classes. A copied class list drifts the first time
  the label changes, and the lint warns on one (`estiva/no-copied-look`).

## What it owns

Nothing. It only draws. Clicks and keys are yours.

## Props

<Controls of={SectionLabelStories.Default} />