# Banner

Mensagem persistente em largura total para status global, manutenção ou ação requerida.

> 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/callout.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>Manutenção programada</AlertTitle>
      <AlertDescription>
        O sistema ficará indisponível sábado às 22h por até 30 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>Manutenção programada</AlertTitle>
    <AlertDescription>
      O sistema ficará indisponível sábado às 22h por até 30 minutos.
    </AlertDescription>
  </Alert>
</template>
```

**HTML (copy-first)**

```html
<div role="status" class="itps-banner itps-banner--info">
  <span class="itps-banner__icon" aria-hidden="true">
    <i class="ti ti-bulb" aria-hidden="true"></i>
  </span>
  <div class="itps-banner__content">
    <span class="itps-banner__title">Dica!</span>
    <span class="itps-banner__text">Sistema atualizado às 14h. Novos recursos no histórico de versões.</span>
  </div>
  <a href="#" class="itps-banner__action">
    <span>Ver mudanças</span>
    <i class="ti ti-arrow-right" aria-hidden="true"></i>
  </a>
</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/banner
```

**terminal · Vue 3/Nuxt 4**

```sh
pnpm dlx shadcn-vue@latest add https://dsystem.sinapse.org.br/r/vue/banner.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` quando o aviso fizer parte da interface da aplicação. Para uma faixa persistente no topo do layout, posicione o `Alert` no shell da página.

Para HTML ou wrappers finos, use `itps-banner` quando precisar do contrato copy-first em largura total. Banner é persistente e global; não substitui validação de campo, Callout local ou Toast transitório.

## Exemplos

### Estrutura

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

### Status e ação

Use `itps-banner--info`, `itps-banner--success`, `itps-banner--alert` e `itps-banner--error` para representar severidade. Use ação apenas quando houver uma próxima etapa clara.

**HTML (copy-first)**

```html
<div class="flex w-full flex-col gap-2">
  <div role="status" class="itps-banner itps-banner--success">
    <span class="itps-banner__icon" aria-hidden="true">
      <i class="ti ti-check" aria-hidden="true"></i>
    </span>
    <div class="itps-banner__content">
      <span class="itps-banner__title">Sucesso!</span>
      <span class="itps-banner__text">Prontuário salvo e sincronizado.</span>
    </div>
  </div>

  <div role="status" class="itps-banner itps-banner--alert">
    <span class="itps-banner__icon" aria-hidden="true">
      <i class="ti ti-alert-triangle" aria-hidden="true"></i>
    </span>
    <div class="itps-banner__content">
      <span class="itps-banner__title">Atenção!</span>
      <span class="itps-banner__text">Token de acesso expira em 3 dias.</span>
    </div>
    <a href="#" class="itps-banner__action">
      <span>Renovar agora</span>
      <i class="ti ti-arrow-right" aria-hidden="true"></i>
    </a>
  </div>

  <div role="alert" class="itps-banner itps-banner--error">
    <span class="itps-banner__icon" aria-hidden="true">
      <i class="ti ti-alert-circle" aria-hidden="true"></i>
    </span>
    <div class="itps-banner__content">
      <span class="itps-banner__title">Erro!</span>
      <span class="itps-banner__text">Falha de sincronização. Tentando novamente...</span>
    </div>
  </div>
</div>
```

## API copy-first

| Classe/atributo | Uso |
|-----------------|-----|
| `itps-banner` | Faixa persistente em largura total. |
| `itps-banner--info`, `itps-banner--success`, `itps-banner--alert`, `itps-banner--error` | Status visual. |
| `itps-banner__icon`, `itps-banner__content`, `itps-banner__title`, `itps-banner__text`, `itps-banner__action` | Anatomia interna. |
| `role="status"` | Avisos persistentes e informativos. |
| `role="alert"` | Falhas que precisam ser anunciadas imediatamente. |
| `aria-hidden="true"` | Esconde ícones decorativos de tecnologias assistivas. |

## Acessibilidade

Use `role="status"` para mensagens informativas persistentes e `role="alert"` somente quando a falha precisar interromper a fila de anúncio. Mantenha ícones com `aria-hidden="true"` e não dependa só da cor para comunicar estado.

O texto da ação deve ser específico, como `Ver mudanças` ou `Renovar agora`. Evite empilhar muitos banners; mais de dois avisos globais competem entre si.