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

<Meta of={RailItemStories} />

# RailItem

One tile of an icon rail: the icon in its hover tile, a 9px label under
it. **Rail** is its shell — the 64px strip the tiles stand in, with no
border and no surface of its own.

<Canvas of={RailItemStories.InTheRail} />

## When

- An app whose navigation is a narrow icon strip beside the content, with
  a handful of top-level places.
- `active` fills the tile (and some themes give the icon their
  interactive colour), plus `aria-current="page"`.
- The rail pairs with the **floating TopBar** (AppShell's `floating`
  variant): the menu button in the bar's `menu` slot collapses it, the
  app's name or mark rides in `logo` beside it. Collapsing is the
  caller's — the rail only gets given less room (or none) to stand in.

## When not

- Entries that need readable labels or counts → **NavItem** in a
  **Sidebar**.
- More places than a handful — a rail without room stops being glanceable;
  use the Sidebar.

## How

```tsx
import { Rail, RailItem } from '@estiva-app/ui'

<Rail>
  <RailItem href="#/desk" label="Desk" icon={<IconNote size={16} stroke={1.5} />} active={at('desk')} />
  <RailItem href="#/people" label="People" icon={<IconUsers size={16} stroke={1.5} />} active={at('people')} />
</Rail>
```

- Both render plain anchors and a `nav` region. Under **AppProvider**'s `navigate`
  a click changes page without a reload; compute `active` from the location
  where you place each item.
- Icons are 16px at stroke 1.5.

- A tile is 64px wide and 48px tall: the 16px icon in its 32px square, over its
  9px label.

## 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 |
|---|---|---|
| Marks the current place for assistive technology when `active` | `aria-current` |  |
| Keeps its 48px in a scrolling column | `shrink-0` |  |

## Props

<Controls of={RailItemStories.Default} />