NotificationCenter
Sininho com a lista
Vazio e carregando
import { NotificationCenter } from '@rivocode/ui'Quando usar
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.
<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.
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
onItemClicke, se ela não estava lida,onMarkReadjunto, e fecha o painel. onMarkReadliga o botão de marcar em cada não lida, sem abrir.onMarkAllReadliga 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
itemssozinho.filtereonFilterChangecontrolam, para quem prefere buscar as não lidas no servidor.
Os finais da consulta
- Carregando (
isLoading): a lista vira marca de lugar, comaria-busy, e o leitor ouve "Carregando…". O vazio não aparece enquanto o dado não chegou. - Vazio: um
EmptyStateque diz "Nenhuma notificação", ou "Tudo lido" quando o filtro de não lidas esvaziou. - Mais páginas:
hasMorecomonLoadMoreliga o "Carregar mais" no fim;isLoadingMorefaz 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 doDataTable, e o aviso é anunciado ao leitor de tela.
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. OToastpassa 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, ouBanner, 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.
<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.
API
| Prop | Tipo | Padrão |
|---|---|---|
itemsobrigatóriaAs notificacoes ja carregadas, da mais nova para a mais antiga. | NotificationItem[] | sem padrão |
alignDe que lado do sininho o painel se alinha, na mesa. | "end" | "start" | "end" |
classNamesClasse 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). | Partial<Record<"empty" | "error" | "filters" | "footer" | "header" | "item" | "list" | "panel" | "trigger", string>> | sem padrão |
defaultFilterO filtro ao montar, quando ninguem controla. | NotificationFilter | "all" |
defaultOpenO painel aberto ao montar, quando ninguem controla. | boolean | false |
filterO filtro, controlado: `all` ou `unread`. | NotificationFilter | sem padrão |
hasMoreHa mais para carregar: liga o "Carregar mais" no fim da lista. | boolean | false |
isErrorA busca falhou. | boolean | false |
isLoadingA primeira carga ainda nao voltou: a lista vira marca de lugar, e o leitor ouve "Carregando". | boolean | false |
isLoadingMoreA proxima pagina esta chegando: o botao gira e nao aceita clique. | boolean | false |
labelsOs textos da peca, para trocar o idioma ou o termo. | Partial<NotificationCenterLabels & NotificationCenterErrorLabels> | sem padrão |
maxO teto do numero no sininho: acima dele sai "99+". | number | 99 |
nowO agora das datas relativas, para teste e para renderizacao no servidor. | Date | sem padrão |
onFilterChangeChamado quando a pessoa troca o filtro. | ((filter: NotificationFilter) => void) | sem padrão |
onItemClickChamado quando a pessoa escolhe uma notificacao. | ((item: NotificationItem) => void) | sem padrão |
onLoadMoreChamado pelo "Carregar mais". | (() => void) | sem padrão |
onMarkAllReadLiga o "Marcar todas como lidas" no topo do painel. | (() => void) | sem padrão |
onMarkReadLiga o botao de marcar como lida em cada nao lida. | ((id: string) => void) | sem padrão |
onOpenChange | ((open: boolean) => void) | sem padrão |
onRetryLiga o "Tentar de novo" do erro. | (() => void) | sem padrão |
openO painel aberto, controlado. | boolean | sem padrão |
unreadCountQuantas nao lidas existem, quando o servidor sabe mais do que a pagina carregada. | number | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.