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

<Meta of={LinkStories} />

# Link

A link, in one of four looks. It is a real anchor with a real address, and
the app decides how it navigates.

<Canvas of={LinkStories.AllVariants} />

## When

- **It takes the size and colour of the text around it**: put it inside that
  text.
- **`text`** — a link written inside text: the theme's link colour, always
  underlined, dimming on hover.
- **`quiet`** — a title or a time that is also a link. It takes the colour and
  size of the text it sits in, and underlines on hover.
- **`underlined`** — a short "open it there" beside a note. It takes the
  note's colour, is always underlined, and brightens on hover.
- **`plain`** — a box or a row that is a link as a whole. No look of its own:
  what it wraps draws itself.
- `external` — another site or app: it opens in a new tab, with
  `noopener noreferrer`.
- **`cover`** — a row that opens one thing wherever you click it: an item in a
  list, a row of a table. The link covers the row, and the keyboard ring goes
  round the whole row.

<Canvas of={LinkStories.Cover} />

## When not

- An action — something happens, nothing is navigated to → **Button**.
- A row of a sidebar → **NavItem**. A tile of a rail → **RailItem**.
- The trail back up → **Breadcrumb**.
- A link that looks like an icon button → **IconButton** with `href`.
- A word standing for a person or a thing, drawn in a small box → **InlineChip**
  with `href`.
- A box that is one link → **Card** with `href`. `cover` is for a row that has
  no frame of its own.
- `cover` on a row whose parts each open something different, or a row with
  nothing to open. A row with only a second link inside it (a chip, say) is
  fine: see How.
- Stretching a link over its row by hand (`after:absolute`): the lint refuses
  it. Use `cover`.

## How

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

<p className="text-body-2">
  Read <Link href="https://example.com" external>the guide</Link> first.
</p>

<h3 className="text-body-2 font-semibold text-text-primary">
  <Link href={itemUrl} variant="quiet" onClick={navigate}>Item one</Link>
</h3>
```

- It renders a plain anchor and passes every anchor prop through. Under
  **AppProvider**'s `navigate`, a plain click on an address in the app changes page
  without a reload; without it, a router app passes `onClick`, prevents the
  default and navigates. The `href` stays a real address, so a modified click
  or a new tab still works.
- `quiet` and `underlined` set no size and no colour at rest: put them inside
  the text whose look they should take.
- `plain` wraps a block: give the Link `className="block"` and let the child
  draw the border, the fill and the hover.
- If your router also exports a `Link`, rename one of them on import.

- `truncate` keeps a title that is a link on one line, cut with an ellipsis.
  Its size and colour still come from the text around it.

- `cover` covers the nearest box that is `relative`: give the row `relative`.
  The row keeps its own size, fill and hover; the link only adds the layer
  and the ring. Pointing anywhere on the row counts as pointing at the link,
  so `quiet` underlines the title while the row is hovered.
- A second link inside the row comes **after** the covering link and is
  `relative` itself, so it sits above the layer. A **Chip** with `href` already
  is.

```tsx
<div className="relative flex h-9 items-center gap-3 px-3 hover:bg-bg-hover">
  <Link href={itemUrl} variant="plain" cover onClick={navigate}>Item one</Link>
  <Chip href={groupUrl} label="Group" onClick={navigate} />
</div>

<tr className="relative">
  <td><Link href={itemUrl} variant="quiet" cover>Item one</Link></td>
  <td>…</td>
</tr>
```
- `quiet`, `underlined` and `plain` take their size and colour from where they
  sit, so put those on your own element around the link, not on the link —
  the lint refuses a look passed in `className`.

## 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 |
|---|---|---|
| Says what it is to assistive technology: a link | `role="link"` | ✓ |
| Is reachable with Tab | a `tabIndex` | ✓ |

## Props

<Controls of={LinkStories.Text} />