# Banner

Aviso de **página**: uma faixa de largura total, no topo da área que ela
governa, que fica até o motivo dela acabar. Manutenção programada, fatura em
atraso, modo de teste, conta em verificação.

```tsx
<Banner
  tone="warning"
  title="Você está no modo de teste"
  description="Os pagamentos feitos aqui não cobram cartão de verdade."
/>
```

Ela diz respeito à conta, ao produto ou à sessão inteira, e não a um trecho do
conteúdo. Por isso encosta nas bordas da área, sem canto de cartão, com uma
linha neutra embaixo.

## Tom e papel

`info`, `success`, `warning` e `danger`, os quatro tons de estado dos tokens.
O tom decide três coisas ao mesmo tempo: a cor, o ícone e o papel para o leitor
de tela.

- `danger` e `warning` saem com `role="alert"`, e interrompem o leitor.
- `info` e `success` saem com `role="status"`, e esperam a frase terminar.

É a mesma regra do `Alert`, pelo mesmo motivo: interromper alguém para dizer
"sua conta foi verificada" é falta de educação com quem depende do leitor.

**Cor nunca é o único sinal**, e por isso o ícone vem sozinho: `Info`,
`CheckCircle2`, `TriangleAlert` e `CircleX`, o par canônico do lucide. `icon`
troca o desenho (uma chave inglesa para manutenção, por exemplo), e `icon={null}`
tira. Ele sai sempre `aria-hidden`: o texto ao lado já diz o que ele desenha.

## Título, descrição e ações

`description` é obrigatória e é o corpo: o que aconteceu e o que a pessoa faz a
respeito. `title` é opcional, sai na cor do tom e, quando existe, dá nome à
faixa.

`actions` recebe os botões, à direita do texto na mesa e embaixo dele no
celular. Use `Button` com `size="sm"` e `variant="secondary"`: a borda dele é a
fronteira medida contra o fundo dos quatro tons, nos dois temas. Rótulo longo
quebra dentro do botão em vez de empurrar a página para o lado, e a faixa cabe
em 320px, que é a tela de quem usa zoom de 400%.

```tsx
<Banner
  tone="danger"
  title="Fatura em atraso"
  description="A fatura de agosto venceu há 5 dias. O acesso da equipe será suspenso em 10/10."
  actions={
    <Button size="sm" variant="secondary">
      Pagar com Pix
    </Button>
  }
/>
```

## Que a pessoa dispensa

`onDismiss` liga o xis no fim da faixa, com o nome "Fechar aviso" (ou o que
`labels.dismiss` disser). **Quem some com a faixa é quem chamou**: a peça não
guarda estado nenhum, e lembrar que a pessoa já dispensou (nesta sessão, ou para
sempre) é decisão do produto, não da faixa.

```tsx
const [open, setOpen] = useState(true)

{open && (
  <Banner
    tone="info"
    title="Manutenção programada"
    description="O agendamento online fica fora do ar domingo, das 2h às 4h."
    onDismiss={() => setOpen(false)}
  />
)}
```

O que bloqueia não se dispensa. Uma fatura que vai suspender a conta continua
na tela até ser paga: tirá-la é resolver o que ela aponta.

## Dentro de um painel

`flush` é a faixa que mora dentro de um `Card`, de um `Sheet` ou de um
`Dialog`, encostada nas bordas dele: o modo de teste de uma conta mostrado no
cartão daquela conta, o aviso de que os dados de um painel estão atrasados.
Ela vai como filha direta do painel, sem respiro em volta, e acerta a linha e o
canto pela posição:

- **no topo**, pega os cantos de cima do painel e fica só com a linha de baixo;
- **no meio**, entre o cabeçalho e o conteúdo, ganha a linha de cima também;
- **no fim**, fica só com a de cima, porque a borda do painel já fecha.

```tsx
<Card>
  <Banner
    flush
    tone="warning"
    title="Você está no modo de teste"
    description="Os pagamentos feitos aqui não cobram cartão de verdade."
  />
  <CardHeader>
    <CardTitle>Pagamentos</CardTitle>
  </CardHeader>
</Card>
```

Sem `flush`, o canto quadrado da faixa vaza pelo canto arredondado do cartão, e
a linha de baixo dobra a borda dele quando a faixa é a última coisa ali. Se o
aviso fala só de um campo ou de uma tabela dentro do cartão, e não do cartão
inteiro, é `Alert`.

A faixa decide entre empilhar e pôr as ações ao lado do texto pela largura
DELA, e não pela da janela: dentro de um cartão estreito numa tela larga, ela
empilha.

## Partes

`classNames` alcança cada nó pelo nome: `icon`, `content` (a coluna do texto),
`title`, `description`, `actions` e `dismiss`.

## Quando não usar

- **Aviso sobre um trecho do conteúdo** é `Alert`. O `Alert` mora junto do que
  ele fala (o formulário cujo certificado vence, a tabela que veio incompleta),
  e o `Banner` fala da página ou da conta inteira. Se o aviso some quando a
  pessoa troca de tela, era `Alert`.
- **Confirmação do que acabou de acontecer** é `Toast`. O `Toast` passa, e o
  `Banner` fica: uma faixa "pedido enviado" no topo da tela ainda está lá quando a
  pessoa volta dez minutos depois, e ela lê aquilo como o estado de agora.
- **Decisão que precisa de resposta antes de seguir** é `AlertDialog`. O
  `Banner` informa e deixa trabalhar; o `AlertDialog` bloqueia a tela até a
  pessoa escolher.

E não empilhe três faixas no topo. Se há mais de um aviso de página ao mesmo
tempo, mostre o mais grave e deixe os outros para a tela onde eles importam.

## No React Native

Traduz, com os mesmos quatro tons, o mesmo `title`, `description`, `actions` e `onDismiss`, e o xis com o mesmo nome acessível ("Fechar aviso"). `title` e `description` são `string`, porque texto no nativo mora dentro de um `Text`.

**A urgência sai por região viva.** `danger` e `warning` saem com `accessibilityRole="alert"` e anúncio imediato; `info` e `success` saem em região viva educada, que espera a frase terminar. É a mesma divisão do `role` do web. No iOS, onde a região viva não existe, título e descrição saem pelo anúncio do sistema: nos tons urgentes também ao aparecer, e nos quatro a cada troca de texto.

**O ícone não vem sozinho.** O pacote nativo não traz biblioteca de ícones, então o `icon` é opcional e a forma que pinta na cor do tom é a função: `icon={({ color, size }) => <TriangleAlert color={color} size={size} />}`. As ações ficam embaixo do texto, que é onde cabem na largura do telefone.

**`flush` é só o topo do painel.** A faixa pega os cantos de cima do `Card` e fica com a linha de baixo, como no web. O web acerta a linha também no meio e no fim do painel, pela posição do filho; o React Native não tem seletor de posição, então no meio ou no fim a linha que falta entra por `className`.

As partes vestem pelo mesmo `classNames` do web, as seis: `icon`, `content`, `title`, `description`, `actions` e `dismiss`.

## Importação

```tsx
import { Banner } from '@rivocode/ui'
```

## Exemplos

### Tons

```tsx
import { Banner, Button, Card, CardContent, CardDescription, CardHeader, CardTitle } from '@rivocode/ui'
import { Wrench } from 'lucide-react'
import { useState } from 'react'

export function Tones() {
  return (
    <div className="flex flex-col gap-3">
      <Banner
        tone="info"
        title="Manutenção programada"
        description="O agendamento online fica fora do ar domingo, 28/09, das 2h às 4h."
      />
      <Banner
        tone="success"
        description="Sua conta foi verificada. Os pagamentos em produção estão liberados."
      />
      <Banner
        tone="warning"
        title="Você está no modo de teste"
        description="Os pagamentos feitos aqui não cobram cartão de verdade."
      />
      <Banner
        tone="danger"
        title="Fatura em atraso"
        description="A fatura de agosto venceu há 5 dias. O acesso da equipe será suspenso em 10/10."
      />
    </div>
  )
}
```

### Com ações

```tsx
import { Banner, Button, Card, CardContent, CardDescription, CardHeader, CardTitle } from '@rivocode/ui'
import { Wrench } from 'lucide-react'
import { useState } from 'react'

export function WithActions() {
  return (
    <Banner
      tone="danger"
      title="Fatura em atraso"
      description="A fatura de agosto venceu há 5 dias. O acesso da equipe será suspenso em 10/10."
      actions={
        <>
          <Button size="sm" variant="secondary">
            Ver fatura
          </Button>
          <Button size="sm" variant="secondary">
            Pagar com Pix
          </Button>
        </>
      }
    />
  )
}
```

### Que a pessoa dispensa

```tsx
import { Banner, Button, Card, CardContent, CardDescription, CardHeader, CardTitle } from '@rivocode/ui'
import { Wrench } from 'lucide-react'
import { useState } from 'react'

export function Dismissible() {
  const [open, setOpen] = useState(true)

  if (!open) {
    return (
      <p className="text-sm text-fg-muted">
        A faixa foi dispensada. Quem some com ela é quem chamou, e não a peça.
      </p>
    )
  }

  return (
    <Banner
      tone="info"
      icon={<Wrench />}
      title="Manutenção programada"
      description="O agendamento online fica fora do ar domingo, 28/09, das 2h às 4h."
      onDismiss={() => setOpen(false)}
    />
  )
}
```

### Dentro de um cartão

```tsx
import { Banner, Button, Card, CardContent, CardDescription, CardHeader, CardTitle } from '@rivocode/ui'
import { Wrench } from 'lucide-react'
import { useState } from 'react'

export function InsidePanel() {
  return (
    <Card>
      <Banner
        flush
        tone="warning"
        title="Você está no modo de teste"
        description="Os pagamentos feitos aqui não cobram cartão de verdade."
      />
      <CardHeader>
        <CardTitle>Pagamentos</CardTitle>
        <CardDescription>Os últimos 30 dias.</CardDescription>
      </CardHeader>
      <CardContent>
        <p className="text-sm text-fg-muted">Nenhum pagamento no período.</p>
      </CardContent>
    </Card>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `description` | `ReactNode` | sim |  | - | O que aconteceu e o que a pessoa faz a respeito. |
| `actions` | `ReactNode` |  |  | - | Os botoes da faixa, a direita do texto e embaixo dele no celular. |
| `classNames` | `Partial<Record<"actions" \| "content" \| "description" \| "dismiss" \| "icon" \| "title", string>>` |  |  | - |  |
| `flush` | `boolean` |  | `false` | - | A faixa mora dentro de um painel (`Card`, `Sheet`, `Dialog`), encostada nas bordas dele, e nao no topo da pagina. |
| `icon` | `ReactNode` |  |  | - | Troca o icone do tom. |
| `labels` | `Partial<BannerLabels>` |  |  | - | Os textos da peca, para trocar o idioma: `dismiss` e o nome do xis, "Fechar aviso" sem ele. |
| `onDismiss` | `(() => void)` |  |  | - | Liga o xis de fechar, no fim da faixa. |
| `title` | `ReactNode` |  |  | - | A frase curta em negrito, antes da descricao. |
| `tone` | `"danger" \| "info" \| "success" \| "warning"` |  | `"info"` | - | O tom decide a cor, o icone padrao e o papel para o leitor de tela: `danger` e `warning` saem `role="alert"` e interrompem; `info` e `success` saem `role="status"` e esperam a frase terminar. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [Alert](/componentes/alert.md)
- [Bacalhau](/componentes/bacalhau.md)
- [Badge](/componentes/badge.md)
- [CookieConsent](/componentes/cookie-consent.md)
- [EmptyState](/componentes/empty-state.md)
- [Illustration](/componentes/illustration.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
