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

<Meta of={ReactionPickerStories} />

# ReactionPicker

The reactions on offer, to choose one from — icon buttons holding emoji, on a
**Toolbar**. **`Reaction` is the answer; this is the question.**

<Canvas of={ReactionPickerStories.Default} />

## When

- **Offering a reaction** — from a control on a card, or from a `Toolbar` of
  actions. This is the case it exists for, and the only one.
- **However many are on offer.** The row is whatever `options` holds; nothing
  here caps or wraps it.

<Canvas of={ReactionPickerStories.FromATrigger} />

## When not

- **Showing the reactions that have been made** — the pills with their counts,
  in a row on the card → **Reaction**. That is the answer; this only asks.
  Which reactions are yours is *its* state, not this one's.
- Any other strip of controls → **Toolbar**, which this is built on.
- A list of verbs → **Menu**.

## How

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

<Popover side="top" align="right" trigger={reactButton} ariaLabel="Reactions" className="w-auto" contentClassName="p-1">
  <ReactionPicker
    surface={false}
    options={[
      { emoji: '👍', label: 'Makes sense' },
      { emoji: '🎉', label: 'Congrats' },
    ]}
    onSelect={react}
  />
</Popover>
```

- **The vocabulary is yours.** Which emoji an app offers, and what each one
  means, is product knowledge — so it arrives as `options`, and every option
  owes a `label`.
- **`label` is not decoration.** The emoji is `aria-hidden`, for the same
  reason it is on `Reaction`: a glyph read aloud is noise, and its spoken name
  differs per screen reader. The label is what a screen reader says and what
  the tooltip shows, so write the *meaning* — "Makes sense", not "thumbs up".
- **`onSelect` reports the emoji**, which is what an app stores. What happens
  to it — a new reaction, or one of yours removed — is the caller's.
- **It opens above the control that was pressed**, not below: the thing being
  reacted to is underneath. `Popover`'s `side="top"`.
- **It draws the box**, from `Toolbar` — so it floats correctly on its own.
  Inside a `Popover`, which draws that box already, pass `surface={false}`.
- **It is one Tab stop**, because it is a `Toolbar`. The hand-written version
  it replaces was one stop per emoji, inside a hover panel — five things to
  Tab past to reach anything after the card.

### What it produces

Picking puts a **Reaction** in the row on the card — the pill with the count
and, when it is yours, the accent fill. The picker asks; the pill answers.

<Canvas of={ReactionPickerStories.AndWhatItProduces} />

## 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 |
|---|---|---|
| Everything a Toolbar owns: one Tab stop, arrow keys between the reactions, wrapping at the ends | a key handler, or `tabIndex` on each reaction |  |

## Keys

| Input | What happens |
|---|---|
| Tab | onto the row — once, however many reactions are offered |
| ← / → | move between them, and wrap at the ends |
| Enter / Space | choose the focused one |
| Tab again | leaves the row entirely |

The keys are `Toolbar`'s, and its gap is this one's: **Home and End do
nothing.**

## Props

<Controls of={ReactionPickerStories.Default} />