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

<Meta of={PersonTriggerStories} />

# PersonTrigger

The person, as the button that opens a menu. Two shapes, one component:
the **row** — face · name · 14px chevron on a 32px button with a hover
fill — and **`compact`** — the face alone, 36px, no chevron and no hover
fill, because the face fills the whole control.

<Canvas of={PersonTriggerStories.Row} />

<Canvas of={PersonTriggerStories.Compact} />

## When

- The account trigger in a top bar — either shape.
- Any control whose meaning is "this person, opened".
- What it opens is not its business: pair it with **IdentityMenu** for the
  ready-made account menu, or your own **Menu**.

## When not

- Showing a person without opening anything → **Person**.
- Choosing a person from a list → **Select** or **ChipInput**.

## How

```tsx
import { Menu, PersonTrigger } from '@estiva-app/ui'

<Menu trigger={<PersonTrigger name={me.name} picture={me.picture} />}>
  …
</Menu>
```

- **Hand it to the menu and write nothing else.** Since stage 4 a `Menu` owns
  its trigger, so the open state, the toggle, `aria-expanded`, the placement
  and the focus return are all its. The `onMouseDown` + `stopPropagation`
  guard this page used to show is gone with the trap it worked around.
- `open` is still there for a caller driving something that is not a `Menu`;
  it holds the row's hover fill and feeds `aria-expanded`. Under a `Menu` it
  is unnecessary — the trigger carries `data-popup-open`, which holds the
  same fill.
- **The accessible name comes from the person, in both shapes.** The row is
  named by its visible name, and the `compact` face — which has no visible
  text — takes the same name through an `aria-label` of its own, so nothing
  is owed. Without it that face would announce **"AD"**: the initials, read
  as text. Pass an `aria-label` only to name what it *opens* rather than who
  it shows; `IdentityMenu`'s compact shape says "Account menu".
- It is a native `<button>` on Base UI's Button: it takes a `ref` and every
  native button prop.

## 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 |
|---|---|---|
| Is a button: Tab reaches it, Enter and Space call your `onClick` | a clickable `<div>` |  |
| Names itself from the person's name, and says whether what it opens is open (`open`) | `aria-label` or `aria-expanded` |  |
| Keeps its 32px in a scrolling column | `shrink-0` |  |

## Keys

| Key | Does |
|---|---|
| Tab | Onto it. |
| Space / Enter | Your `onClick`: open what it opens. |

## Props

<Controls of={PersonTriggerStories.Row} />