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

<Meta of={NavItemStories} />

# NavItem

One row of a sidebar: an optional 16px icon, a label, and an optional
count — a muted mono number whose tooltip says what it counts.

<Canvas of={NavItemStories.WithIconAndCount} />

## When

- The entries of a **Sidebar** — top-level places, and the rows of a
  labelled group.
- `active` marks where the route is: the selected tab's neutral fill, and
  `aria-current="page"` for assistive tech.
- A count is a number of **one** thing, and `countLabel` says which ("18
  open", "5 active"). A `0` or an absent count draws nothing — that is
  this row's rule; a *tab* draws its zero, and both rulings stand.

<Canvas of={NavItemStories.ZeroDrawsNothing} />

- A row with things to do to it — move it, rename it — takes them as
  `menu`: pass `MenuItem`s, and the row draws the ⋮, shows it while the row
  is pointed at or keyboard-focused, and moves the count aside for it. On a
  screen with no hover the ⋮ always shows, and the count or dot under it
  stays aside: the row reads as it does under a pointer.

<Canvas of={NavItemStories.WithMenu} />

- One thing done often enough to stay in sight — take the row off a list —
  is `action`: an icon, its tooltip and its handler, the shape of a
  **SectionHeader**'s actions. It shows with the ⋮, in the count's place, and
  before the ⋮ when the row has a menu too. One, never a row of them: a second
  thing to do goes in the menu.

<Canvas of={NavItemStories.WithAction} />

- A row with rows under it takes them as `children`: more `NavItem`s. The
  row stays a link; while it is pointed at or focused, its icon becomes the
  arrow that folds them, in the icon's own place, and they slide shut. For a
  whole tree from one list, use **NavTree**.

<Canvas of={NavItemStories.WithRowsUnder} />

- A word that helps only while the row is pointed at — where the item comes
  from — is `hint`: pass a neutral **Chip**. It shows left of the count, and
  the label ends with "…" before it instead of running under it.

<Canvas of={NavItemStories.WithHintLongLabel} />

- A sentence about the item, for whoever points at it, is `tooltip`: it
  shows in the package's tooltip while the **label** is pointed at, and the
  row stays one line. The ⋮ and the `action` keep their own tooltips. Absent
  or blank, there is none. A screen with no hover never shows it, so it can
  carry nothing the row needs.

<Canvas of={NavItemStories.LabelTooltip} />

- Something new on the row is `unread`: its words and icon brighten, the
  label is set in medium, and the **UnreadDot** sits at the right.
  `urgent` with it draws the warning badge in the dot's place. Say "unread"
  in the row's own accessible name too: a dot reads as nothing.

<Canvas of={NavItemStories.Unread} />

## When not

- An icon rail's tile → **RailItem**.
- Switching views inside a page → **Tabs**.
- A row in a popover → **MenuItem**.

## How

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

<NavItem
  href="/documents"
  label="Documents"
  icon={<IconListDetails size={16} stroke={1.5} />}
  count={openCount}
  countLabel={`${openCount} open`}
  active={current === 'documents'}
/>
```

- It renders a plain anchor, and every anchor prop passes through. Under
  **AppProvider**'s `navigate` a click changes page without a reload, so no
  wrapper is needed: compute `active` from the location where you place it.
- The label truncates; the count never gives up its width.
- `menu` is the items only: `menu={<MenuItem label="Move to Folder…" onClick={move} />}`.
  The ⋮'s name is `More options for {label}` unless `menuLabel` says otherwise.
- `action` is `{ icon, tooltip, onClick }`: `action={{ icon: <IconX size={16} stroke={1.5} />, tooltip: 'Remove from list', onClick: remove }}`.
  Its name is `{tooltip}: {label}`.
- `children` start open; `defaultOpen={false}` starts them folded, and
  `open` with `onOpenChange` hands the state to the app. The arrow's name is
  `Hide what is under {label}` or `Show what is under {label}`.
- `hint` takes room only while it shows, so a label at rest keeps its full
  width.
- The ⋮ lands on what is at the right: the count, or the dot. With nothing
  there it keeps no room at rest, so the label has the row's whole width,
  and takes its 24px slot only while it shows.
- `active` is `bg-nav-active`, the current row in a sidebar, which each theme
  sets for itself.

- A row is 32px tall, 8px in on each side, 8px between the icon and the label,
  the label 14px regular (medium when unread), 8px corners as a **MenuItem**'s.

## 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 32px in a scrolling column | `shrink-0` |  |
| Shows a ⋮ over the count while pointed at, focused or open, and keeps the row's hover look under it | a positioned `IconButton` + `Menu` over the row, `group-hover` reveals |  |
| Turns its icon into the arrow that folds `children` while pointed at or focused, and slides them | a positioned `IconButton` over the icon, open state, `group-hover` reveals, an indented box |  |
| Tells assistive technology whether its rows are open | `aria-expanded`, `aria-controls` |  |
| Shows `hint` only while pointed at or focused, and makes the label give way | a positioned chip over the row, `group-hover` reveals |  |
| Draws the dot or the badge for `unread` and `urgent`, and brightens the row | an **UnreadDot** placed by hand, a weight or colour passed in |  |

## Keys

| Key | Does |
|---|---|
| Tab | the link, then its arrow (with `children`), then its ⋮ (with `menu`) |
| Enter, Space | on the arrow: folds or unfolds the rows under it |

The rows are not an ARIA tree: there are no arrow keys between rows yet.

## Props

<Controls of={NavItemStories.Default} />