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

<Meta of={AvatarStories} />

# Avatar

A person's face: their picture, or their initials on a colour that is
theirs, or — when there is no name to take initials from — a silhouette.

<Canvas of={AvatarStories.Sizes} />

## When

- Anywhere a person appears at a glance: a row, a card, a picker, a byline.
- The scale is 16 · 18 · 20 · 24 · 32 · 36 (default): 18 in a group's reply
  row, 20 in a **Person**. Pick from it rather than inventing sizes.

## When not

- Several people at once → **AvatarGroup**.
- The face beside a name, with nothing else on the line → **Person**. A byline
  that sets the name its own way — bold, with a time — is an Avatar beside its
  own text.
- The face as a button that opens a menu → **PersonTrigger**.

## How

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

<Avatar name={person.name} src={person.picture} size={24} />
```

- The caller resolves `src`. While the picture loads the tile stays empty;
  once it arrives it fills the tile; if it fails, the initials show — nothing
  to handle. It is Base UI's `Avatar`, which watches the picture load.
- Initials come from a **name, never a key**: the first letter of the first
  two words, skipping words that open with a symbol. An unnamed person is
  the silhouette, not a `?` — a question mark reads as an error badge.
- The initials are centred on the capitals themselves — cap height to
  baseline — not on the line of text around them. A single face can
  still sit up to half a pixel off: the screen rounds text to its pixel grid
  wherever the tile lands.
- The colour behind initials is per person, chosen from the name, the same
  everywhere they appear. It is a fallback palette, not a token — themes
  have no say in it.
- The corner is `rounded-sm` and stays that way. A surface that wants
  rounder geometry wraps the Avatar concentrically — it does not override
  the Avatar's own radius.

### What it says out loud

**A face is silent by default**, and that is the important half: almost every
face in the suite sits beside the name it belongs to — in a `Person`, in a
`MenuItem`'s `leading`, in a row — and a picture that spoke there would say the
name twice. It used to: a `Person`
inside a button announced **"AD Ana Duarte"** (the initials read as text), and
with a picture **"Ana Duarte Ana Duarte"**.

**`label` names a face that stands on its own** — the compact `PersonTrigger`,
a stack of members — and the tile becomes one image with one name.

```tsx
<Avatar name={person.name} />                     {/* beside a name: silent */}
<Avatar name={person.name} label={person.name} /> {/* alone: says who it is */}
```

<Canvas of={AvatarStories.Palette} />

- **Planned:** a Byline part — face · name · time — in migration stage 7.

- `initialsFor(name)` and `hueFor(name)` give the same initials and colour where
  the part itself cannot be drawn.

## 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 |
|---|---|---|
| Shows initials from the name when there is no picture, or when it fails to load | an `onError`, or initials of your own |  |

## Props

<Controls of={AvatarStories.Initials} />