# NotificationCenter

O sininho do cabeçalho: diz quantas notificações a pessoa ainda não leu e abre
a lista delas. Na mesa a lista é um painel ancorado ao sino; no celular, uma
folha que sobe de baixo, como a do `DatePicker`.

```tsx
<NotificationCenter
  items={notificacoes}
  onMarkRead={(id) => marcarComoLida(id)}
  onMarkAllRead={marcarTodas}
  onItemClick={(item) => navegar(item)}
/>
```

**A peça não busca nada.** A lista entra por `items`, e o que a pessoa faz sai
por callback: marcar uma, marcar todas, abrir uma, trocar o filtro, pedir a
próxima página. Quem guarda o `read` e quem fala com o servidor é a aplicação.

## Cada notificação

| Campo         | O que faz                                                            |
| ------------- | -------------------------------------------------------------------- |
| `id`          | identifica nos callbacks                                             |
| `title`       | o que aconteceu; em negrito enquanto não foi lida                    |
| `description` | o detalhe, em até duas linhas                                        |
| `time`        | quando; sai como `RelativeTime`, "há 5 minutos", com a data no `title` |
| `read`        | já foi lida                                                          |
| `href`        | para onde leva; com ele, a linha vira link                           |
| `render`      | o elemento de link do router, no lugar do `<a href>`                 |
| `icon`        | o símbolo à esquerda; sem ele, o sino                                |
| `tone`        | pinta o símbolo no texto do estado: `info`, `success`, `warning`, `danger` |

Num app com router, `href` sozinho recarrega a página inteira no clique. Passe o
link do router em `render`, a mesma forma do `SidebarMenuItem` e do `Link`: a
linha veste o elemento com o desenho dela, e o clique continua marcando como
lida e fechando o painel.

```tsx
import { NavLink } from 'react-router'

<NotificationCenter
  items={avisos.map((aviso) => ({ ...aviso, render: <NavLink to={aviso.rota} /> }))}
  onMarkRead={marcarLida}
/>
```

A não lida tem três sinais, e nenhum deles é só cor: o ponto, o negrito e, para
o leitor de tela, "Não lida:" antes do título.

## O contador

O número do sino é o `Indicator` da casa, e ele some quando não há nada para
ler: uma pastilha com zero chama atenção para dizer que não há nada. Acima de
`max` (99) sai "99+".

O nome do botão diz a contagem por extenso, "3 notificações não lidas", e vira
só "Notificações" quando zera. Uma região viva educada repete a frase quando o
número muda, e quem usa leitor de tela fica sabendo que chegou coisa nova sem
precisar voltar ao sino.

`unreadCount` vence a conta dos itens carregados: é para quando o servidor sabe
que há 140 não lidas e a página só trouxe 20.

## Ler, marcar e filtrar

- **Abrir uma notificação conta como ler.** O clique chama `onItemClick` e,
  se ela não estava lida, `onMarkRead` junto, e fecha o painel.
- `onMarkRead` liga o botão de marcar em cada não lida, sem abrir.
- `onMarkAllRead` liga o "Marcar todas como lidas" no topo, que fica
  desabilitado quando não há o que marcar. Texto longo nele quebra a linha, e
  não vaza do painel com a tela ampliada.
- **Marcar não derruba o foco.** O botão de marcar some quando a notificação
  vira lida, e o foco vai para o link ou o botão da mesma linha; sem eles, para
  o próximo "Marcar como lida"; sem nenhum, para o filtro. O "Marcar todas"
  desabilita com o foco nele, e o foco vai para o filtro. Quem navega pelo
  teclado continua dentro do painel, e não volta ao começo da página.
- O filtro "Todas" e "Não lidas" filtra `items` sozinho. `filter` e
  `onFilterChange` controlam, para quem prefere buscar as não lidas no servidor.

## Os finais da consulta

- **Carregando** (`isLoading`): a lista vira marca de lugar, com `aria-busy`, e
  o leitor ouve "Carregando…". O vazio não aparece enquanto o dado não chegou.
- **Vazio**: um `EmptyState` que diz "Nenhuma notificação", ou "Tudo lido"
  quando o filtro de não lidas esvaziou.
- **Mais páginas**: `hasMore` com `onLoadMore` liga o "Carregar mais" no fim;
  `isLoadingMore` faz o botão girar e recusar o segundo clique.
- **Erro** (`isError`): sem nada carregado, o aviso toma o lugar da lista, com
  "Tentar de novo" quando há `onRetry`; com linhas na tela, elas ficam e um
  aviso acima delas diz que podem estar desatualizadas. Os nomes são os do
  `DataTable`, e o aviso é anunciado ao leitor de tela.

```tsx
const { mutate: markRead } = useMutation({ mutationFn: markNotificationRead })

<NotificationCenter
  items={query.data?.items ?? []}
  isLoading={query.isLoading}
  isError={query.isError}
  onRetry={query.refetch}
  unreadCount={query.data?.unread}
  hasMore={query.hasNextPage}
  onLoadMore={query.fetchNextPage}
  isLoadingMore={query.isFetchingNextPage}
  onMarkRead={markRead}
/>
```

## Partes

`classNames` alcança cada nó pelo nome: `trigger` (o sino), `panel` (o painel
ou a folha), `header`, `filters`, `list`, `item`, `footer`, `empty` e `error`
(o aviso de falha, no lugar da lista ou acima dela).

## Textos

`labels` troca todos os textos: `title`, `trigger`, `unreadCount` (a função que
diz a contagem), `unreadItem`, `markRead`, `markAllRead`, `filter`, `all`,
`unread`, os dois vazios (`emptyTitle`, `emptyDescription`, `emptyUnreadTitle`,
`emptyUnreadDescription`), `loadMore` e os três da falha: `error` (nada
carregou), `stale` (falhou, e o que está na tela pode estar velho) e `retry`.

## Quando não usar

- **Aviso que precisa ser visto agora** é `Toast`. O `Toast` passa na frente
  da tela; a notificação espera no sino até a pessoa ir buscar.
- **Aviso que fica na tela até o motivo acabar** é `Alert`, junto do trecho
  de que fala, ou `Banner`, no topo da página. O que está no sino some da
  vista assim que o painel fecha.
- **Só o número em cima de um ícone** é `Indicator`. Se não há lista para
  abrir, o sininho promete o que não tem.
- **O histórico de um registro** (quem criou, quem cancelou o pedido) é
  `Timeline`. A notificação é da pessoa; a linha do tempo é da coisa.

## No React Native

Traduz, com a lista numa `Sheet` que sobe de baixo, que é o que o web já faz no celular. `items`, `unreadCount`, `onMarkRead`, `onMarkAllRead`, o filtro, `hasMore`, `onLoadMore`, `isLoadingMore`, `isLoading` e `labels` têm o mesmo nome e o mesmo sentido, e os textos saem da mesma fonte.

**`open` é controlado**, com `onOpenChange`, como em todo o pacote nativo. **O sino entra por `icon`**, do `lucide-react-native`, e a forma que pinta na cor do botão é a função: `icon={({ color, size }) => <Bell color={color} size={size} />}`.

**A linha não é link.** No celular quem navega é o router, então a notificação não tem `href`: `onItemPress` recebe o item e decide para onde ir. Abrir continua contando como ler, e a folha fecha.

A contagem é o nome do botão ("3 notificações não lidas"), e quando ela muda o leitor de tela ouve a frase nova pelo anúncio do sistema.

```tsx
<NotificationCenter
  items={notificacoes}
  open={aberto}
  onOpenChange={setAberto}
  icon={sino}
  onItemPress={abrir}
  onMarkRead={marcar}
/>
```

As partes vestem pelo mesmo `classNames` do web: `trigger`, `panel`, `header`, `filters`, `list`, `item`, `empty` e `error`, o aviso de falha. O `className` continua no botão do sino, o mesmo nó de `trigger`. `footer` não existe aqui: o "Carregar mais" fica direto na folha, sem faixa própria.

**A falha tem lugar, com os mesmos nomes do web: `isError` e `onRetry`.** Sem nada carregado, o erro toma o lugar da lista, com o "Tentar de novo"; com linhas na tela, elas ficam e um aviso acima diz que podem estar desatualizadas. Os textos são `labels.error`, `labels.stale` e `labels.retry`, nos dois pacotes.

## Importação

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

## Exemplos

### Sininho com a lista

```tsx
import { NotificationCenter, type NotificationItem } from '@rivocode/ui'
import { CreditCard, Rocket, UserPlus } from 'lucide-react'
import { useState } from 'react'

const MINUTE = 60_000

const FIRST_PAGE: NotificationItem[] = [
  {
    id: '1',
    title: 'Versão 2.4 publicada',
    description: 'O projeto Atlas está no ar com a nova tela de cadastro.',
    time: Date.now() - 5 * MINUTE,
    read: false,
    tone: 'success',
    icon: <Rocket />,
  },
  {
    id: '2',
    title: 'O cartão da assinatura vence em 5 dias',
    description: 'Atualize antes de 29/09 para o plano não ser interrompido.',
    time: Date.now() - 3 * 60 * MINUTE,
    read: false,
    tone: 'warning',
    icon: <CreditCard />,
  },
  {
    id: '3',
    title: 'Ana Beatriz entrou na equipe',
    time: Date.now() - 2 * 24 * 60 * MINUTE,
    read: true,
    icon: <UserPlus />,
  },
]

const OLDER: NotificationItem[] = [
  {
    id: '4',
    title: 'Relatório de agosto pronto',
    time: Date.now() - 20 * 24 * 60 * MINUTE,
    read: true,
  },
]

export function Center() {
  const [items, setItems] = useState(FIRST_PAGE)
  const [loadingMore, setLoadingMore] = useState(false)
  const hasMore = items.length < FIRST_PAGE.length + OLDER.length

  function markRead(id: string) {
    setItems((current) => current.map((item) => (item.id === id ? { ...item, read: true } : item)))
  }

  function loadMore() {
    setLoadingMore(true)
    setTimeout(() => {
      setItems((current) => [...current, ...OLDER])
      setLoadingMore(false)
    }, 800)
  }

  return (
    <NotificationCenter
      items={items}
      onMarkRead={markRead}
      onMarkAllRead={() => setItems((current) => current.map((item) => ({ ...item, read: true })))}
      onItemClick={(item) => console.log('abrir', item.id)}
      hasMore={hasMore}
      onLoadMore={loadMore}
      isLoadingMore={loadingMore}
    />
  )
}
```

### Vazio e carregando

```tsx
import { NotificationCenter, type NotificationItem } from '@rivocode/ui'
import { CreditCard, Rocket, UserPlus } from 'lucide-react'
import { useState } from 'react'

export function States() {
  return (
    <div className="flex items-center gap-4">
      <NotificationCenter items={[]} labels={{ trigger: 'Notificações (vazio)' }} />
      <NotificationCenter items={[]} isLoading labels={{ trigger: 'Notificações (carregando)' }} />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `items` | `NotificationItem[]` | sim |  | - | As notificacoes ja carregadas, da mais nova para a mais antiga. |
| `align` | `"end" \| "start"` |  | `"end"` | - | De que lado do sininho o painel se alinha, na mesa. |
| `classNames` | `Partial<Record<"empty" \| "error" \| "filters" \| "footer" \| "header" \| "item" \| "list" \| "panel" \| "trigger", string>>` |  |  | - | Classe por parte: `trigger` (o sininho), `panel`, `header`, `filters`, `list`, `item` (cada linha), `footer` (o "Carregar mais"), `empty` e `error` (o aviso de falha, no lugar da lista ou acima dela). |
| `defaultFilter` | `NotificationFilter` |  | `"all"` | - | O filtro ao montar, quando ninguem controla. |
| `defaultOpen` | `boolean` |  | `false` | - | O painel aberto ao montar, quando ninguem controla. |
| `filter` | `NotificationFilter` |  |  | - | O filtro, controlado: `all` ou `unread`. |
| `hasMore` | `boolean` |  | `false` | - | Ha mais para carregar: liga o "Carregar mais" no fim da lista. |
| `isError` | `boolean` |  | `false` | - | A busca falhou. |
| `isLoading` | `boolean` |  | `false` | - | A primeira carga ainda nao voltou: a lista vira marca de lugar, e o leitor ouve "Carregando". |
| `isLoadingMore` | `boolean` |  | `false` | - | A proxima pagina esta chegando: o botao gira e nao aceita clique. |
| `labels` | `Partial<NotificationCenterLabels & NotificationCenterErrorLabels>` |  |  | - | Os textos da peca, para trocar o idioma ou o termo. |
| `max` | `number` |  | `99` | - | O teto do numero no sininho: acima dele sai "99+". |
| `now` | `Date` |  |  | - | O agora das datas relativas, para teste e para renderizacao no servidor. |
| `onFilterChange` | `((filter: NotificationFilter) => void)` |  |  | - | Chamado quando a pessoa troca o filtro. |
| `onItemClick` | `((item: NotificationItem) => void)` |  |  | - | Chamado quando a pessoa escolhe uma notificacao. |
| `onLoadMore` | `(() => void)` |  |  | - | Chamado pelo "Carregar mais". |
| `onMarkAllRead` | `(() => void)` |  |  | - | Liga o "Marcar todas como lidas" no topo do painel. |
| `onMarkRead` | `((id: string) => void)` |  |  | - | Liga o botao de marcar como lida em cada nao lida. |
| `onOpenChange` | `((open: boolean) => void)` |  |  | - |  |
| `onRetry` | `(() => void)` |  |  | - | Liga o "Tentar de novo" do erro. |
| `open` | `boolean` |  |  | - | O painel aberto, controlado. |
| `unreadCount` | `number` |  |  | - | Quantas nao lidas existem, quando o servidor sabe mais do que a pagina carregada. |

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)
- [CookieConsent](/componentes/cookie-consent.md)
- [EmptyState](/componentes/empty-state.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
