FilterBar
Padrão
A linha guardada
Filtro que o app trava
Estreito, com rolagem
Enquanto a consulta refaz
import { FilterBar } from '@rivocode/ui'Quando usar
A fileira dos filtros aplicados, o botão de limpar e a contagem: as três
coisas que toda listagem remonta à mão em volta do DataTable.
Ela não gerencia consulta. Não sabe o que é uma página, um queryKey nem
um refetch, pela mesma razão que o DataTable não conhece React Query:
estado de consulta é arquitetura de aplicação, e a casa decidiu deixá-lo de
fora. A peça recebe filters, apresenta o que recebeu e avisa quando alguma
coisa saiu.
const [filters, setFilters] = useState<AppliedFilter[]>([
{ id: 'status', label: 'Situação', value: 'Em separação' },
{ id: 'customer', label: 'Cliente', value: 'Mariana Lopes' },
])
<FilterBar filters={filters} onFiltersChange={setFilters} />
onFiltersChange recebe o que sobrou, no xis e no limpar. É o mesmo par
do onValueChange do TagsInput, e sozinho ele já basta. onRemove existe
ao lado dele para quem precisa saber qual filtro saiu, e recebe o objeto
inteiro; onClear dispara antes do onFiltersChange, para a telemetria
que conta "quantas vezes alguém desiste de tudo". O limpar entrega a lista só
com os filtros travados, e não a lista vazia (veja "Filtro que o app trava").
Cada filtro é { id, label, value }. O id é a chave estável: é por ele que
a peça remove, e não por índice. O label é o campo (Cliente) e o value é
o escolhido (Mariana Lopes); os dois juntos são o que o leitor de tela
ouve no xis, porque "Remover" repetido quatro vezes não distingue nada.
O tipo do filtro é o seu, desde que tenha os campos de AppliedFilter. A peça
é genérica nele: onRemove e onFiltersChange devolvem o mesmo tipo, com os
campos próprios, e quem trata a remoção não precisa converter de volta.
type Filtro = AppliedFilter & { campo: 'situacao' | 'cliente' }
<FilterBar
filters={filtros}
onRemove={(filtro) => limparCampo(filtro.campo)}
onFiltersChange={setFiltros}
/>
A linha fica, mesmo vazia
Sem filtro nenhum a barra continua ocupando a linha, com "Nenhum filtro
aplicado" em texto apagado. A tela que pula quando o primeiro filtro entra é um
defeito conhecido, e o Tracker do React Native já pagou por ele: lá a linha
de leitura existe desde o primeiro quadro justamente para o espaço ficar
reservado e nada saltar no primeiro toque. Aqui é a mesma conta, e ela custa
uma altura de controle (--rc-control-sm), a mesma da densidade escolhida no
provider, e não um número cravado.
Quem realmente não pode gastar a linha passa reserve={false}. O aviso ao
leitor de tela continua montado mesmo assim: uma região viva precisa existir
antes da mudança para anunciá-la, e uma barra que se desmonta ao perder o
último filtro anunciaria o silêncio.
Quando os filtros não cabem
A 390px, três filtros não cabem. A barra rola na horizontal dentro da própria moldura, com o "limpar" ancorado fora do trecho que rola.
Não quebra linha porque a altura da barra passaria a depender de quantos filtros existem: quatro fichas de "Cliente: Mariana Lopes" viram quatro linhas, e a listagem (que é o conteúdo) desce para fora da dobra. A barra é moldura, e moldura que cresce até metade da tela deixou de ser moldura.
Não colapsa em "+3" porque a barra existe justamente para dizer que o resultado está filtrado. Filtro escondido atrás de um contador é a origem do chamado "sumiram meus dados", e desdobrá-lo pediria uma segunda superfície flutuante para uma fileira de fichas.
Cada ficha corta o valor com reticências em 10rem, então um valor comprido encolhe a si mesmo em vez de empurrar os vizinhos para fora do alcance. O teclado chega a todos: o navegador rola até o xis que recebe foco.
Quando nenhum xis é alcançável (barra só de filtros travados, ou barra
disabled) e a fileira realmente transborda, o trecho que rola vira
uma parada de tabulação, senão o teclado não teria como chegar ao que está fora
da vista. As duas condições são necessárias: disabled existe para tirar
controles do caminho enquanto a consulta refaz, e uma fileira que cabe inteira
na linha não tem um pixel para rolar. Tabular para dentro de uma lista que não
sai do lugar é tabular para lugar nenhum.
Sendo parada, ela tem nome: "Filtros aplicados: role para ver todos", o
label da fileira mais o que fazer ali. Sem nome, o leitor de tela anuncia
"lista" e deixa a pessoa adivinhar onde caiu. O texto se troca por
labels.scroll, que recebe o label e devolve a frase.
A borda esmaece quando há mais
Rolar resolve o alcance e não resolve o aviso. Com seis filtros de razão social,
a 390px cabe uma ficha e meia, e a segunda é cortada pela borda da moldura
no meio da letra. Reticências não resolvem, porque quem corta é o rolador, e
não a ficha: o truncamento em 10rem da FilterChip acontece dentro da
pílula, e a borda corta o que sobrou.
A borda que tem conteúdo escondido atrás esmaece (mask-image, 1,5rem de
dissolução) e some sozinha quando não há mais o que rolar daquele lado: no
começo só a direita, no meio as duas, no fim só a esquerda, e nenhuma quando
tudo coube. Nada sai da fileira: as seis fichas continuam lá, alcançáveis pelo
arrasto e pela tabulação, que é a decisão que esta seção defende desde o
começo.
O esmaecido foi escolhido por ser a única pista que não custa largura, e largura é exatamente o que falta numa linha de 390px que já divide espaço com o "limpar":
- Setas de rolar comeriam uns 56px de alvo justamente na largura onde o problema é pior, e serviriam só ao ponteiro: o dedo já arrasta e o teclado já tabula. Ainda precisariam da mesma medida de rolagem que o esmaecido usa, então não substituem o custo: somam a ele.
- Um contador "+3" ao lado do limpar duplicaria uma contagem que já está na tela (é o mesmo motivo pelo qual o contador separado não existe), e "+3" é o vocabulário do colapso: quem o vê tenta clicar esperando desdobrar a fileira, que é a segunda superfície flutuante recusada acima.
O botão não mente. "Limpar 6 filtros" ao lado de três fichas visíveis conta os filtros aplicados, que é a pergunta que importa antes de tocar nele. Lidos juntos, o botão e a borda esmaecida fecham a conta: seis aplicados, três à vista, o resto continua para a direita.
O esmaecido não come o anel de foco. O trecho que rola leva scroll-padding da
mesma 1,5rem, então o xis que recebe foco sempre para depois da dissolução; e
quando a fileira é só de filtros travados e o rolador vira a parada de
tabulação, o esmaecido sai enquanto ele está focado, para o anel aparecer
inteiro.
Por classNames.list a medida se redesenha (mask-r-from-*), para quem quiser
outra dissolução.
O foco depois de tirar um filtro
O xis que recebe o toque sai do DOM junto com a ficha, e sem cuidado o foco
voltaria para o <body> a cada remoção: numa barra de seis, seis reinícios no
topo do documento para quem navega por teclado.
A peça escolhe onde o foco pousa, nesta ordem:
- o xis da ficha seguinte, que é a que ocupou o lugar da que saiu. É o que deixa tirar seis filtros seguidos sem soltar o teclado;
- o "limpar", quando a que saiu era a última da fileira;
- o xis da ficha anterior, quando não há limpar (
clearFrom={Infinity}, ou contagem que caiu abaixo da régua); - o trecho que rola (ou a raiz
role="group", quando o último filtro saiu e a fileira inteira desmontou). Nos dois casos otabindex="-1"é posto na hora e devolvido noblur: pouso de emergência não deixa parada de tabulação nova para trás.
Controle travado não entra na conta. A barra que fica disabled no mesmo passo
da remoção (a consulta já refazendo) teria mandado o foco para um xis que não
pode recebê-lo, que é o <body> de novo por outro caminho; nesse caso o pouso
salta para o primeiro degrau que aceita foco.
O foco só se move se ele estava na fileira. Quem clicou com o ponteiro tendo o cursor em outro lugar da página não é puxado para dentro da barra.
O limpar aparece a partir de dois
Com um filtro só, o xis da própria ficha faz exatamente o mesmo, à mesma distância do dedo: um segundo controle para o mesmo efeito não ensina nada e ainda come 110px de uma linha de 390px. O botão passa a valer quando "tirar um por um" vira trabalho.
Ele mostra a contagem ("Limpar 3 filtros") e é lá que a contagem visível
mora. Um contador separado disputaria a largura escassa com as fichas, que são
a contagem já visível; no botão ele dobra de função e diz o tamanho do estrago
antes do toque. Para outra régua, clearFrom={1} deixa o botão sempre, e
clearFrom={Infinity} tira-o de vez.
Filtro que o app trava
removable: false mostra o filtro sem xis. É o escopo que a aplicação impõe
(a filial da pessoa, o tenant, o semestre letivo aberto): ele precisa aparecer,
porque explica o resultado, e sair dele não é escolha de quem lê. Hoje esse
filtro costuma ser simplesmente omitido, e aí a lista mente sobre o próprio
recorte.
O limpar não leva o travado junto: onFiltersChange recebe só os filtros
com removable: false, e a contagem do botão conta só os que ele tira. Com a
filial travada e dois filtros escolhidos, o botão diz "Limpar 2 filtros", e a
régua do clearFrom também mede só os removíveis. Depois do limpar o foco
pousa na raiz role="group", com o mesmo tabindex="-1" de emergência do
pouso depois do xis.
Enquanto a consulta refaz
disabled trava todos os xis e o limpar de uma vez. É o estado em que a lista
já foi pedida de novo e ainda não voltou: sem ele, o segundo toque dispara uma
consulta que a primeira ainda vai sobrescrever.
O grupo leva aria-disabled, e o leitor de tela anuncia a fileira inteira como
indisponível, e não só cada xis. Cada ficha leva data-disabled na raiz, a
mesma marca que as outras peças usam para o inativo: o texto apagado é de
componente inativo, que a WCAG 1.4.3 isenta do contraste de texto.
O nome da fileira
label é a única porta do nome, e o padrão é "Filtros aplicados". Passar
aria-label direto é recusado pelo tipo, porque label existe exatamente
para isso e porque o mesmo texto batiza duas coisas: a fileira e
o trecho que rola, quando ele vira parada de tabulação. Duas portas dariam dois
nomes ao mesmo lugar. Quem precisa apontar
para um título que já está na tela usa aria-labelledby, que a peça não
sobrescreve.
As partes
classNames veste cada nó pelo nome: list é o trecho que rola, item é o
<li> de cada filtro, chip é a raiz da ficha, clear é o botão de limpar e
empty é o texto da linha guardada. Sem eles a única saída seria [&_li], que
amarra a sua tela à árvore interna da peça.
A fileira sai como <ul> com role="list" explícito. O list-style: none do
preflight tira a semântica de lista no Safari, e é ela que faz o leitor de tela
anunciar "3 itens" sem que ninguém conte nada.
Movimento
Só a ficha de filtro aplicada depois da montagem cresce ao entrar (animate-pop, --rc-duration-fast); as que já estavam nascem paradas.
Quando não usar
Quando as opções são poucas, fixas e cabem à vista, use ToggleGroup: escolher
e desescolher acontece no mesmo lugar, num toque, e não há o que resumir depois.
A FilterBar é para o caso oposto: o filtro foi escolhido em outro lugar
(um Combobox, um DateRangePicker, uma folha inteira de filtros) e a
listagem precisa dizer o que sobrou valendo.
Quando o filtro é o próprio texto que a pessoa digita, use TagsInput: lá a
lista nasce do campo e o campo é a peça. Aqui a peça não tem campo nenhum, de
propósito.
No React Native
Traduz, e é onde a peça vale mais: listagem no celular é onde filtro dói. As decisões de desenho já tinham sido tomadas pensando em 390px, então quase tudo atravessa: rola na horizontal, não quebra linha e não colapsa em +3.
O limpar fica FORA do que rola. Se ele rolasse junto, o controle que existe para desfazer tudo seria o único que exige rolar até o fim para achar. Ele ancora à direita da fileira, e o size="sm" do Button nativo já entrega o alvo de 44pt sozinho.
A linha reservada passa a ser medida em dedo. No web ela guarda a altura de --rc-control-sm; aqui guarda 44pt, que é uma altura de alvo de toque. Não há token de controle do lado de cá. A fileira tem a mesma altura vazia e cheia, pelo mesmo motivo do Tracker: a tela não pode pular quando o primeiro filtro entra.
A região viva é um Text único que acumula as duas funções, em vez dos dois nós do web: duplicar abriria um gap morto na fileira. accessibilityLiveRegion é do Android e do web; no iOS, onde ela não existe, a mesma frase sai pelo announceForAccessibility, e só quando a contagem muda, como a região viva.
RTL foi verificado, e a maior parte o próprio React Native resolve. A fileira e a ficha já são espelhadas pelo Yoga quando a locale é da direita para a esquerda, e o repouso da rolagem já para na borda onde a leitura começa: inverter de novo seria o erro clássico de espelhar duas vezes. O contentOffset que chega ao JavaScript é sempre distância física a partir da esquerda, nos dois sentidos e nas duas plataformas, então a régua marca o lado físico que tem conteúdo além dele, e não troca de lado.
Em repouso, antes do primeiro arraste, a régua já marca o lado certo nos dois sentidos de leitura: o quanto já passou é contado a partir do início da leitura, e não da esquerda, então não depende do primeiro evento de rolagem, que o iOS não emite em repouso.
A borda esmaece no web; aqui ela é uma régua. mask-image não existe no React Native, e um esmaecido de verdade só sairia de duas formas. Um peer novo (expo-linear-gradient, MaskedView), que uma barra de filtros não pode cobrar, porque no celular peer é módulo nativo a ligar e reconstruir. Ou um gradiente pintado NA cor da superfície de trás, que a peça não tem como saber: no tema escuro, surface sobre bg vira um borrão claro por cima das fichas. O gradiente em si até estava ao alcance, porque o react-native-css compila linear-gradient para o experimental_backgroundImage que o RN traz de fábrica; o que falta é a máscara, e sem ela não há alfa por pixel.
O que ficou: uma régua de 1pt em border-strong encostada na borda que tem conteúdo escondido, que aparece e some sozinha conforme a rolagem, não custa largura nenhuma e não come o arrasto que começa nela. É a mesma pista, mais dura, e é o mesmo inset 1px com que o DataTable marca a coluna congelada no web.
Cai a parada de tabulação do web, porque não há foco de teclado aqui. As partes vestem pelo mesmo classNames do web: list no conteúdo do que rola, item, chip, clear e empty, esta só na linha reservada.
Genérico no tipo do filtro, como no web. FilterBar<TFilter> devolve o tipo de quem chama no onRemove e no onFiltersChange: com { id, label, value, field: "status" }, o field volta sem conversão.
API
| Prop | Tipo | Padrão |
|---|---|---|
filtersobrigatóriaOs filtros de agora. | TFilter[] | sem padrão |
classNamesClasse por parte: `list`, `item`, `chip`, `clear`, `empty`. | Partial<Record<"chip" | "clear" | "empty" | "item" | "list", string>> | sem padrão |
clearFromA partir de quantos filtros removiveis o "limpar" aparece; o travado nao conta nem sai. | number | 2 |
disabledTrava todos os xis e o limpar, para a consulta que refaz nao aceitar um segundo toque. | boolean | sem padrão |
labelO nome da fileira para o leitor de tela. | string | "Filtros aplicados" |
labelsOs textos que a peca escreve: `remove` no xis, `clear` no botao de limpar, `status` na regiao viva, `empty` na linha guardada e `scroll` no trecho que rola, quando ele vira parada de tabulacao. | { remove?: ((filter: string) => string) | undefined; clear?: ((total: number) => string) | undefined; status?: ((total: number) => string) | undefined; scroll?: ((name: string) => string) | undefined; empty?: ReactNode; } | sem padrão |
onClearChamado quando o "limpar" e apertado, antes do `onFiltersChange`. | (() => void) | sem padrão |
onFiltersChangeRecebe o que sobrou, tanto no xis quanto no limpar. | ((filters: TFilter[]) => void) | sem padrão |
onRemoveO filtro que saiu, com o objeto inteiro, quando o xis dele e apertado. | ((filter: TFilter) => void) | sem padrão |
reserveGuarda a altura da linha quando nao ha filtro nenhum, para a tela nao pular quando o primeiro entra. | boolean | true |
sizeA altura das fichas. | "md" | "sm" | "md" |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.