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

<Meta of={TabsStories} />

# Tabs

A row of tabs for switching between views of one thing. The selected tab
is a neutral fill, not the accent — selection is a place, not a highlight.

<Canvas of={TabsStories.WithCounts} />

## When

- Views of the same subject: all / unread / flagged, list / grid.
- A tab's `count` is a muted mono number after the label, sharing its
  baseline — the one way a number sits beside a label. A count of `0` is
  still drawn ("Assigned to me · 0" is an answer); an absent count draws
  nothing.
- A tab with `unread` draws the **UnreadDot** after its label (and count),
  without the dot's 24px slot so the row keeps one height, and says "new" in
  its accessible name.
- Two sizes: `default` (14px) and `small` (12px, the denser geometry).

<Canvas of={TabsStories.WithUnread} />

<Canvas of={TabsStories.WithAZero} />

## When not

- Going to a different place → **Link**, **NavItem** or **Breadcrumb**.
- Choosing a value that gets saved → **Select**.
- Actions → **Button**s; a tab never *does*, it *shows*.

## How

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

<Tabs
  tabs={[
    { id: 'all', label: 'All', count: total },
    { id: 'unread', label: 'Unread', count: unread },
  ]}
  active={tab}
  onChange={setTab}
/>
```

- Generic over the id type — `onChange` hands back your union, not a
  string, and only for a person's choice.
- Built on Base UI Tabs: `role="tablist"` / `role="tab"` with
  `aria-selected`, one Tab stop for the row, arrow keys between the tabs.
  Wiring the panels — what shows for the active tab — is the caller's.
- `className` lands on the outer box, around the row.

- **Name the row** with `aria-label` where an app has more than one, or where
  a screen reader would otherwise announce two "tab lists". A visible heading
  that already names it takes `aria-labelledby` instead. Unnamed is fine for
  the only tab row on a page.

## 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 |
|---|---|---|
| Takes its keys by itself: Home and End select the first and last tab | a key listener on the page | ✓ |
| Moves through its items with the arrow keys: ← → select the next tab, and wrap at the ends | an arrow-key handler | ✓ |
| Says what it is to assistive technology: a set of tabs and their panels | `role="tablist"`, `tab` or `tabpanel` | ✓ |
| Is one Tab stop: Tab lands on the selected tab | a `tabIndex` on each tab |  |

## Keys

| Key | Does |
|---|---|
| Tab | Into the row, onto the selected tab; out of it on the next press. |
| ← → | Select the previous / next tab. The ends wrap. |
| Home / End | Select the first / last tab. |

## Props

<Controls of={TabsStories.NoCounts} />