# Tooltip

> Componentes / Estado e aviso · Estado: **Em andamento** — Implementado e utilizável, mas ainda sem a validação completa de acessibilidade.

Dica curta que aparece no hover e no foco de um controle — o que um ícone faz, o que um campo aceita —, ligada a ele por `aria-describedby`. Some com Esc e não some quando o ponteiro passa para ela (WCAG 1.4.13).

- Função: Estado e aviso
- Também chamado de: dica, balão, tooltip, legenda flutuante
- Mora em: `app/components/molecules/Tooltip.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/Tooltip](https://phorte-design-system.vercel.app/styleguide/peca/Tooltip)
- Ficha no Storybook: [components-complex-tooltip](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-tooltip--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/Tooltip/0](https://phorte-design-system.vercel.app/previa/Tooltip/0)
- Todas as peças: [https://phorte-design-system.vercel.app/llms.txt](https://phorte-design-system.vercel.app/llms.txt)

## Como usar no código

```tsx
import { Tooltip } from '@/app/components/molecules/Tooltip';

<Tooltip conteudo={…}>…</Tooltip>
```

O `…` marca as props obrigatórias — ver *Propriedades*.

## Uso

### Variantes na ficha

1. [Padrão](https://phorte-design-system.vercel.app/previa/Tooltip/0)
2. [Embaixo](https://phorte-design-system.vercel.app/previa/Tooltip/1)
3. [Num botão de ajuda](https://phorte-design-system.vercel.app/previa/Tooltip/2)

Para completar o nome de um controle que já tem nome: o que o botão "Compartilhar" copia, o que conta na carga horária.

### Quando não usar

Para a regra de um campo, use a dica do FormField, que fica à vista. Para uma mensagem que pede atenção, o Alert. Para conteúdo com link ou botão, um Modal ou a própria página.

### Faça

- Ponha um gatilho focável (botão, link, campo) com nome próprio — o botão só-ícone continua com `aria-label`.
- Escreva uma frase curta, sem link nem botão.
- Use `lado="baixo"` quando o gatilho estiver no topo da tela.

### Evite

- Guardar ali informação essencial: no celular não há hover, e a dica só aparece com o foco.
- Tooltip num elemento que não recebe foco (um ícone solto, um texto): quem usa teclado nunca o vê.
- Repetir o nome do botão na dica: o leitor diria duas vezes.

### Anatomia

1. **Gatilho** — O filho, com `aria-describedby` apontando para a dica (somado ao que ele já tiver).
2. **Balão** — Fundo `--ink`, texto `--ink-inverse` 12px, até 256px de largura, com sombra; acima ou abaixo do gatilho.

### Estados

| Estado | O que muda |
| --- | --- |
| Fechado | O balão fica no DOM com `hidden` — o `aria-describedby` continua valendo. |
| Aberto | Esmaece em 150ms, só com movimento liberado. |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| Ponteiro sobre o gatilho | Abre depois de 300ms (`atraso`) — conferido no teste da ficha, com atraso 0. |
| Ponteiro passa para a dica | Continua aberta: o ponteiro está no invólucro — conferido no teste da ficha. |
| Foco no gatilho | Abre na hora; sai com o foco. |
| Esc | Fecha de qualquer lugar sem mover o foco — conferido no teste da ficha. |

### Relacionados

- [FormField](https://phorte-design-system.vercel.app/styleguide/md/FormField.md) — A dica que fica à vista, para a regra do campo.
- [Button](https://phorte-design-system.vercel.app/styleguide/md/Button.md) — O gatilho mais comum — só-ícone, com `aria-label`.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `lado` | `'cima' \| 'baixo'` | `'cima'` | não | Variante do `cva`. |
| `conteudo` | `string` | — | sim | O texto da dica. Curto, sem link nem botão: quem passa o mouse não consegue clicar. |
| `children` | `React.ReactElement<React.HTMLAttributes<HTMLElement>>` | — | sim | O gatilho: **um** elemento focável — botão, link ou campo. A dica é ligada a ele por `aria-describedby`; ele continua precisando de nome próprio (um botão só-ícone leva `aria-label`). |
| `atraso` | `number` | `300` | não | Espera antes de abrir no hover, em ms. No foco abre na hora. |
| `className` | `string` | — | não |  |

### Medidas

| Parte | Valor | Classe |
| --- | --- | --- |
| Largura máxima | 256px | `max-w-64` |
| Distância do gatilho | 8px | `mb-2 · mt-2` |

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--foreground` | #1A1A1A | `bg-ink` |
| `--ink-inverse` | #FAFAFA | `text-ink-inverse` |

## Acessibilidade

### Teclado

| Tecla | Faz |
| --- | --- |
| Tab | Leva o foco ao gatilho e abre a dica; o próximo Tab sai e fecha — conferido no teste da ficha. |
| Esc | Fecha a dica e deixa o foco no gatilho — conferido no teste da ficha. |

### Leitor de tela

- A dica é `role="tooltip"` ligada por `aria-describedby`: o leitor diz o nome do botão e depois a dica ("Compartilhar curso, botão. Copia o link do curso para compartilhar.") — conferido no teste da ficha.
- Cumpre a 1.4.13 inteira: dispensável (Esc), sobrevoável (o ponteiro chega a ela) e persistente (fica enquanto há ponteiro ou foco).

### O que sustenta o estado

Usa os padrões: estatico. Falta ouvir com leitor de tela: estatico.

## Status e recursos

| Tipo | Recurso | Status |
| --- | --- | --- |
| Código | `app/components/molecules/Tooltip.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-tooltip--docs | Disponível |
| Teste de acessibilidade | axe em `npm run test` | No gate de todo commit |
| Leitor de tela | Passada da E33 | Falta ouvir |
| Design | Figma | Desativado até a Fase 2 |

### Histórico

- `fdd10ff` 2026-09-29 — ESTADO: E109 concluida, roteiro final fechado; proximo o merge na main
- Histórico completo no GitHub: https://github.com/srbunnie/Pos-Phorte-Design-System/commits/main/app/components/molecules/Tooltip.tsx