# Callout

Mensagem contextual dentro de uma seção, card ou fluxo de formulário.

> Documentação do Sinapse DS. Snippets shadcn usam os componentes do seu projeto (`@/components/ui/*`); snippets HTML usam as classes `itps-*` do CSS Sinapse (`/css/<versão>/`, veja `/comecar.md`). Componentes do site de documentação não fazem parte do DS.

- Categoria: Feedback
- Status: stable
- Relacionados: /componentes/banner.md, /componentes/toast.md

## Em cada stack

- HTML e Astro: Classes `itps-*` do CSS Sinapse, com todas as variantes desta página.
- React e Vue: Componentes padrão do shadcn (`alert`) com o tema Sinapse: cores, fonte e raio vêm do tema, e as variantes `itps-*` desta página existem só no HTML.

**React/Next (shadcn/ui)**

```tsx
import {
  Alert,
  AlertDescription,
  AlertTitle,
} from '@/components/ui/alert'

export function AlertExample() {
  return (
    <Alert>
      <AlertTitle>Prontuário sincronizado</AlertTitle>
      <AlertDescription>
        Última sincronização há 2 minutos.
      </AlertDescription>
    </Alert>
  )
}
```

**Vue 3/Nuxt 4 (shadcn-vue)**

```vue
<script setup lang="ts">
import {
  Alert,
  AlertDescription,
  AlertTitle,
} from '@/components/ui/alert'
</script>

<template>
  <Alert>
    <AlertTitle>Prontuário sincronizado</AlertTitle>
    <AlertDescription>
      Última sincronização há 2 minutos.
    </AlertDescription>
  </Alert>
</template>
```

**HTML (copy-first)**

```html
<div role="status" class="itps-callout itps-callout--md itps-callout--info">
  <span class="itps-callout__icon" aria-hidden="true">
    <i class="ti ti-bulb" aria-hidden="true"></i>
  </span>
  <div class="itps-callout__content">
    <div class="itps-callout__body">
      <p class="itps-callout__title">Prontuário sincronizado</p>
      <p class="itps-callout__description">Última sincronização há 2 minutos.</p>
    </div>
    <a href="#" class="itps-callout__action">
      <span>Ver log</span>
      <i class="ti ti-arrow-right" aria-hidden="true"></i>
    </a>
  </div>
</div>
```

## Instalação

O comando instala o Alert da sua stack com o tema Sinapse. Configure o registry uma vez por projeto em [Comece por aqui](/comecar).

**terminal · React/Next**

```sh
pnpm dlx shadcn@latest add @sinapse/callout
```

**terminal · Vue 3/Nuxt 4**

```sh
pnpm dlx shadcn-vue@latest add https://dsystem.sinapse.org.br/r/vue/callout.json
```

Sem shadcn, não há instalação por componente: use o CSS Sinapse e as classes da API copy-first desta página.

## Uso

Em React/Next com shadcn/ui e Vue 3/Nuxt 4 com shadcn-vue, use `Alert`, `AlertTitle` e `AlertDescription` para mensagens contextuais dentro da interface. Ele deve ficar perto do conteúdo que explica.

Para HTML ou wrappers finos, use `itps-callout` quando precisar do contrato copy-first com tamanhos, status, ícone e ação. O Callout é contido: para aviso global, use Banner; para feedback transitório, use Toast.

## Exemplos

### Estrutura

| Peça | React/Next e Vue 3/Nuxt 4 | HTML |
|------|--------------------------|------|
| Contêiner | `Alert` | `itps-callout` |
| Título | `AlertTitle` | `itps-callout__title` |
| Descrição | `AlertDescription` | `itps-callout__description` |
| Ícone | ícone no conteúdo | `itps-callout__icon` |
| Ação | botão ou link externo ao `Alert` | `itps-callout__action` |

### Status, tamanho e ação

Use `itps-callout--sm`, `itps-callout--md` e `itps-callout--lg` conforme densidade. Use `itps-callout--info`, `itps-callout--success`, `itps-callout--alert` e `itps-callout--danger` para severidade.

**HTML (copy-first)**

```html
<div class="flex w-full max-w-2xl flex-col gap-3">
  <div role="status" class="itps-callout itps-callout--sm itps-callout--success">
    <span class="itps-callout__icon" aria-hidden="true">
      <i class="ti ti-check" aria-hidden="true"></i>
    </span>
    <div class="itps-callout__content">
      <div class="itps-callout__body">
        <p class="itps-callout__title">Documento enviado com sucesso.</p>
      </div>
    </div>
  </div>

  <div role="status" class="itps-callout itps-callout--md itps-callout--alert">
    <span class="itps-callout__icon" aria-hidden="true">
      <i class="ti ti-alert-triangle" aria-hidden="true"></i>
    </span>
    <div class="itps-callout__content">
      <div class="itps-callout__body">
        <p class="itps-callout__title">Verifique os dados antes de salvar.</p>
        <p class="itps-callout__description">Há campos que podem exigir revisão manual.</p>
      </div>
      <a href="#" class="itps-callout__action">
        <span>Revisar campos</span>
        <i class="ti ti-arrow-right" aria-hidden="true"></i>
      </a>
    </div>
  </div>

  <div role="alert" class="itps-callout itps-callout--lg itps-callout--danger">
    <span class="itps-callout__icon" aria-hidden="true">
      <i class="ti ti-alert-circle" aria-hidden="true"></i>
    </span>
    <div class="itps-callout__content">
      <div class="itps-callout__body">
        <p class="itps-callout__title">Não foi possível conectar ao servidor.</p>
        <p class="itps-callout__description">Tente novamente ou acione o suporte se o erro persistir.</p>
      </div>
      <a href="#" class="itps-callout__action">
        <span>Tentar novamente</span>
        <i class="ti ti-arrow-right" aria-hidden="true"></i>
      </a>
    </div>
  </div>
</div>
```

## API copy-first

| Classe/atributo | Uso |
|-----------------|-----|
| `itps-callout` | Mensagem contextual contida. |
| `itps-callout--sm`, `itps-callout--md`, `itps-callout--lg` | Densidade visual. |
| `itps-callout--info`, `itps-callout--success`, `itps-callout--alert`, `itps-callout--danger` | Status visual. |
| `itps-callout__icon`, `itps-callout__content`, `itps-callout__body`, `itps-callout__title`, `itps-callout__description`, `itps-callout__action` | Anatomia interna. |
| `role="status"` | Mensagens informativas no fluxo da página. |
| `role="alert"` | Falhas que precisam ser anunciadas imediatamente. |
| `aria-hidden="true"` | Esconde ícones decorativos de tecnologias assistivas. |

## Acessibilidade

Use `role="status"` para mensagens informativas que já aparecem no fluxo da página. Use `role="alert"` só para falhas que precisam interromper a fila de anúncio. Mantenha ícones com `aria-hidden="true"` e não dependa só da cor para comunicar estado.

Omita `itps-callout__icon` quando o ícone repetir informação ou disputar atenção com o conteúdo principal. A ação deve ter texto específico, como `Ver log`, `Configurar` ou `Tentar novamente`. Evite empilhar muitos callouts na mesma seção; isso reduz hierarquia e clareza.