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

<Meta of={BreadcrumbStories} />

# Breadcrumb

A trail: where you are, and the way back up. Crumbs, muted slashes
between them, and a tooltip on any crumb that has had to truncate.

<Canvas of={BreadcrumbStories.OnAnItem} />

## When

- The top of a detail page: parents first, the current place last.
- A crumb with an `href` is a link — even the last one, when a page ends
  its trail on somewhere to go. The last item without one is "you are
  here" (`aria-current="page"`).
- `mono` sets a crumb in the mono face for a ref or an id — and a mono
  crumb **never gives up width** to a long name beside it; the name
  truncates, the ref stays whole.

<Canvas of={BreadcrumbStories.LongName} />

- `icon` draws a 16px icon before a crumb — what kind of place it is, so
  a container's name is not read as an item's. Decorative: the trail is
  still read as its labels.

<Canvas of={BreadcrumbStories.WithAnIcon} />

## When not

- Switching between sibling views of one thing → **Tabs**.
- Just a page title → the `h*` type tokens; a one-item trail says
  nothing.

## How

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

<Breadcrumb
  items={[
    { label: 'Documents', href: '/documents' },
    { label: 'Quarterly plan', href: '/documents/12' },
    { label: 'DOC-12', mono: true },
  ]}
/>
```

- A crumb is a **Link**, so it changes page as Link does: through
  **AppProvider**'s `navigate`, or an `onClick` per crumb. The `href` stays a real
  address, so the link can still be copied or opened in a new tab.
- Truncation is re-measured as the trail resizes; the tooltip appears and
  disappears with the room the trail actually has. Give the trail a
  `min-w-0` container so it can truncate at all.
- The separators are `aria-hidden` — the trail reads as its places.

- 6px between each place and its separator.

## 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 |
|---|---|---|
| Shortens a trail that does not fit, and shows a cut crumb in full on hover | truncation code, or a tooltip |  |
| Names itself as a navigation, and marks the last crumb as the current page | `<nav>`, `aria-label` or `aria-current` |  |
| Hides the separators from screen readers, so the trail reads as its places | `aria-hidden` on each separator |  |

## Props

<Controls of={BreadcrumbStories.OnAnItem} />