# CookieConsent

O aviso de consentimento de cookies, no molde da LGPD: um painel preso no pé
da tela, com o texto, o link da política de privacidade e três saídas, "Aceitar
todos", "Recusar não essenciais" e "Personalizar", que abre as categorias uma a
uma.

```tsx
const [choice, setChoice] = useState(() => readChoice())

<CookieConsent
  open={choice === null}
  policyHref="/privacidade"
  onDecision={(next) => {
    saveChoice(next)
    setChoice(next)
  }}
/>
```

**A peça não grava cookie nenhum.** Ela mostra o aviso e devolve a escolha por
`onDecision`; guardar a escolha, carregar só os scripts aceitos e fechar o
aviso é trabalho de quem usa. `open` é controlado: abra quando não há escolha
guardada, ou quando a pessoa pede para rever a dela num link "Preferências de
cookies" do rodapé.

`policyHref` é o endereço da política de privacidade do seu app. Os exemplos que
rodam nesta página passam `"#"` porque este site não tem uma, e o link não
pode levar a uma página que não existe.

## Dentro de uma caixa

O aviso encosta embaixo da janela. Com `contained`, ele encosta embaixo do pai
posicionado mais próximo, e não rola por cima da página: para a prévia do aviso
dentro de um `Card` na tela de configurações, ou para o app que roda numa
moldura própria. O pai precisa de `relative` e de altura.

```tsx
<div className="relative h-80 overflow-hidden rounded-lg border border-border">
  <CookieConsent contained open onDecision={() => {}} policyHref="#" />
</div>
```

Por dentro, a fila dos botões vira linha pela largura do aviso, e não da tela,
nos dois modos.

## A escolha

`onDecision` recebe `{ action, categories }`. `action` diz qual botão decidiu
(`acceptAll`, `rejectOptional` ou `save`), e `categories` traz uma chave por
categoria, com `true` para o que foi aceito:

```tsx
{ action: 'rejectOptional', categories: { necessary: true, analytics: false, marketing: false } }
```

A categoria obrigatória volta sempre `true`, em qualquer um dos três botões.
Guarde também a data e a versão da política que a pessoa viu: se a política
mudar, é a data que diz que a escolha precisa ser pedida de novo.

## Recusar é tão fácil quanto aceitar

"Aceitar todos" e "Recusar não essenciais" saem lado a lado, com o mesmo
tamanho, a mesma variante e o mesmo peso. Nenhum dos dois é o botão de
destaque. É o que o guia de cookies da ANPD pede, e é a diferença entre
consentimento e truque de interface: recusar não pode custar um clique a mais
nem exigir abrir o "Personalizar".

No "Personalizar", só as obrigatórias nascem ligadas. Chave que já vem ligada
não é escolha, e a LGPD pede consentimento ativo. Para quem reabre o aviso,
`defaultValue` recebe a escolha guardada e as chaves começam como a pessoa as
deixou.

## Categorias

Sem `categories`, o aviso traz três, em `defaultCookieCategories`:
**Necessários** (obrigatória, sempre ligada e sem chave de desligar),
**Análise** e **Marketing**. Troque pelas do seu produto, cada uma com o que
faz numa frase:

```tsx
<CookieConsent
  open={open}
  policyHref="/privacidade"
  onDecision={decide}
  categories={[
    { id: 'necessary', label: 'Necessários', description: 'Sessão, segurança e esta escolha.', required: true },
    { id: 'analytics', label: 'Análise', description: 'Quais telas são usadas, sem identificar você.' },
    { id: 'support', label: 'Chat de suporte', description: 'O balão de conversa no canto da tela.' },
  ]}
/>
```

## Foco e teclado

**Ao abrir sozinho, o aviso não tira o foco do lugar.** Quem chega pela página
ou está no meio da leitura continua onde estava: o aviso é mais uma parada do
Tab, e por isso vale renderizá-lo no topo do layout, para ser a primeira. Quem
reabre pelo botão de preferências vai direto para ele, e o leitor de tela lê o
título e o texto: o foco só se move quando estava num botão ou link, que é o
gesto de pedir o aviso. **Ele não prende a página**: é um diálogo não modal (`aria-modal="false"`), sem
fundo escurecido e sem armadilha de foco, e quem quer ler a página antes de
decidir continua lendo. O Tab sai do aviso para a página normalmente.

**Esc não dispensa.** Fechar sem escolher deixaria a pessoa sem saber o que foi
decidido por ela, e o aviso voltaria na próxima página. Quem fecha é a escolha.
Quando o aviso fecha com o foco dentro dele, o foco volta para onde estava
antes de ele abrir.

Ele entra subindo com a curva de entrada dos tokens de movimento e sai com a de
saída, e empilha em `--rc-z-overlay`: acima do conteúdo e de barra grudada, e
abaixo de diálogo e de aviso.

## Partes

`classNames` alcança cada nó pelo nome: `panel`, `title`, `description`,
`policy`, `categories`, `category` e `actions`. `className` veste a faixa
fixa de fora.

## Quando não usar

- **Aviso de página sem escolha** (manutenção, fatura em atraso) é `Banner`.
  O `CookieConsent` existe para colher uma decisão, e o `Banner` só informa.
- **Parede de cookies**, que bloqueia a página até a pessoa aceitar, não é
  este aviso e não é `AlertDialog`: condicionar o acesso ao aceite contraria o
  consentimento livre que a LGPD pede. Se o produto não funciona sem os
  cookies necessários, eles são necessários, e não precisam de aceite.
- **Confirmar que a escolha foi salva** é `Toast`, se for preciso dizer
  alguma coisa. Na maior parte das vezes o aviso sumir já diz.

## No React Native

Não porta, por decisão. Aplicativo não tem cookie de navegador para pedir licença: o consentimento de rastreio no celular é o aviso da própria plataforma, o App Tracking Transparency no iOS, pedido pelo `expo-tracking-transparency`, e a declaração de dados na loja no Android. Um painel desenhado pela biblioteca por cima disso seria um segundo pedido para a mesma coisa.

Se o app abre páginas web num `WebView`, o aviso é o da página, que roda o `@rivocode/ui` do web.

## Importação

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

## Exemplos

### Aceitar, recusar ou personalizar

```tsx
import { Button, CookieConsent, type CookieChoice } from '@rivocode/ui'
import { useState } from 'react'

export function Decide() {
  const [open, setOpen] = useState(false)
  const [choice, setChoice] = useState<CookieChoice | null>(null)

  return (
    <div className="flex flex-col items-start gap-3">
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Preferências de cookies
      </Button>
      <p className="text-sm text-fg-muted">
        {choice
          ? `Última escolha: ${Object.entries(choice.categories)
              .filter(([, accepted]) => accepted)
              .map(([id]) => id)
              .join(', ')}.`
          : 'Nenhuma escolha ainda.'}
      </p>
      <CookieConsent
        open={open}
        policyHref="#"
        defaultValue={choice?.categories}
        onDecision={(next) => {
          setChoice(next)
          setOpen(false)
        }}
      />
    </div>
  )
}
```

### Categorias próprias

```tsx
import { Button, CookieConsent, type CookieChoice } from '@rivocode/ui'
import { useState } from 'react'

export function OwnCategories() {
  const [open, setOpen] = useState(false)

  return (
    <div className="flex flex-col items-start gap-3">
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Abrir o aviso
      </Button>
      <CookieConsent
        open={open}
        policyHref="#"
        title="Sua privacidade"
        description="A loja usa cookies para manter você conectado e, se você deixar, para medir o uso e abrir o chat de suporte."
        categories={[
          {
            id: 'necessary',
            label: 'Necessários',
            description: 'Sessão, segurança e esta escolha.',
            required: true,
          },
          {
            id: 'analytics',
            label: 'Análise',
            description: 'Quais telas são usadas, sem identificar você.',
          },
          {
            id: 'support',
            label: 'Chat de suporte',
            description: 'O balão de conversa no canto da tela.',
          },
        ]}
        onDecision={() => setOpen(false)}
      />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `onDecision` | `(choice: CookieChoice) => void` | sim |  | - | Chamado com a escolha, em qualquer um dos tres botoes. |
| `open` | `boolean` | sim |  | - | Se o aviso esta na tela. |
| `policyHref` | `string` | sim |  | - | O endereco da politica de privacidade. |
| `categories` | `CookieCategory[]` |  |  | - | As categorias do "Personalizar". |
| `classNames` | `Partial<Record<"actions" \| "categories" \| "category" \| "description" \| "panel" \| "policy" \| "title", string>>` |  |  | - | Classe por parte: `panel`, `title`, `description`, `policy`, `categories`, `category` e `actions`. |
| `contained` | `boolean` |  | `false` | - | Prende o aviso ao pai em vez da janela: ele encosta embaixo da caixa posicionada mais proxima (de `relative` nela), e nao rola junto com a pagina por cima de tudo. |
| `defaultValue` | `Record<string, boolean>` |  |  | - | Como cada chave do "Personalizar" comeca. |
| `description` | `ReactNode` |  |  | - | O texto do aviso, antes do link da politica. |
| `labels` | `Partial<Omit<{ title: string; description: string; policy: string; acceptAll: string; rejectOptional: string; customize: string; save: string; required: string; categories: string; }, "description" \| "title">>` |  |  | - | Os textos dos botoes e do link: `policy`, `acceptAll`, `rejectOptional`, `customize`, `save`, `required` (o que acompanha a categoria obrigatoria) e `categories`, o nome da lista do "Personalizar". |
| `title` | `ReactNode` |  |  | - | O titulo do aviso. |

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)
- [Banner](/componentes/banner.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)
