# Filtros e busca

A busca acha pelo texto, o filtro recorta por campo, e os dois moram no
endereço: o que está aplicado fica à vista, sai com um clique e volta quando a
pessoa volta.

## O problema

A pessoa filtra a listagem por situação e cliente, abre um registro, aperta
voltar, e a lista está crua de novo. Ou manda o link para um colega, que abre a
lista inteira. Ou não percebe que há um filtro aplicado desde ontem e acha que
os pedidos sumiram. E o filtro que só aplica num botão "Filtrar" escondido no
fim do painel faz ela marcar cinco opções antes de descobrir que nada mudou.

## Quando usar

Toda listagem que passa de uma tela: a de operação (`DataTable`), o catálogo de
loja, a caixa de entrada, a agenda. A busca entra quando a pessoa sabe o nome
do que procura; o filtro, quando ela sabe o tipo.

| Onde o filtro mora | Quando |
|---|---|
| Na barra acima da lista | até uns quatro campos, os mais usados: situação, período, responsável |
| Num painel lateral na mesa, `Sheet` no celular | mais que isso, ou faixas e listas longas de opção (preço, marca, categoria) |
| No cabeçalho da coluna | só em tabela de dados, e só para o campo daquela coluna |

## Quando não usar

- **Lista de menos de uma tela** não pede filtro: a pessoa vê tudo.
- **Busca que procura no sistema inteiro** (pessoa, pedido, configuração) é o
  `Command` com atalho, e não o campo de uma listagem.
- **Filtro que zera a lista sem avisar**: a opção que não traria nada mostra
  "(0)" ou fica desligada.
- **O vazio do filtro não oferece "criar"**: oferece "Limpar filtros", porque
  quem filtrou quer o filtro de volta.

## As peças

- `SearchInput`: a busca da lista, com o limpar e o atalho.
- `Select`, `Combobox` com `multiple`, `DateRangePicker`, `Slider` de faixa,
  `CheckboxGroup`: os campos do filtro.
- `FilterBar` com `filters` e `onFiltersChange`: a fileira do que está aplicado,
  com o remover de cada um e o "Limpar filtros". É genérico no tipo do filtro:
  `AppliedFilter & { campo: ... }` volta inteiro no `onRemove`.
- `Sheet` sem `side`: o painel de filtros no celular, que sobe de baixo.
- `DataTable` com `filter`, `isFetching`, `noResultsMessage` e `empty`: a lista
  que filtra, revalida sem piscar e distingue vazio de sem resultado.
- `useDebouncedValue`: a busca que espera a pessoa parar de digitar.

## Comportamento

- **O estado vai no endereço.** Busca, filtros, ordem e página são parâmetros
  da URL (`?situacao=aberta&cliente=482&busca=otica&pagina=2`), pelo roteador
  do projeto. É o que faz voltar do registro devolver a mesma lista, o link
  compartilhado abrir o mesmo recorte e o recarregar não perder nada. Lembrar
  entre visitas, com `useLocalStorage`, é outra coisa, e só para a visão que a
  pessoa escolheu como dela.
- **Os aplicados ficam à vista, sempre**, no `FilterBar` acima da lista, com o
  remover de cada um e o "Limpar filtros". No celular, sem reabrir o painel.
- **Na mesa, o filtro aplica na hora**, e a contagem do resultado muda junto.
  A busca aplica depois da pausa, com `useDebouncedValue` entre 250 e 400 ms.
- **No celular, o painel é um `Sheet`**, e o rodapé dele tem o botão que diz
  quantos vai mostrar. Ali o filtro só aplica no botão, porque cada toque
  refazendo a lista atrás da folha não se vê.
- **Filtrar volta para a primeira página**, e mantém o resto.
- **A lista de antes fica enquanto a nova chega**, com o `isFetching`: filtro
  não volta ao esqueleto ([espera.md](https://ds.rivocode.com.br/padroes/espera.md)).
- **Sem resultado é diferente de vazio.** "Nenhuma nota com estes filtros",
  com "Limpar filtros", é o `noResultsMessage`; "Nenhuma nota ainda", com
  "Emitir a primeira", é o `empty`.

```tsx
<div className="flex flex-col gap-3 sm:flex-row sm:items-center">
  <SearchInput
    aria-label="Buscar notas"
    placeholder="Número, cliente ou CNPJ"
    value={search}
    onValueChange={(value) => setParams({ busca: value, pagina: 1 })}
  />
  <Select value={status} onValueChange={(value) => setParams({ situacao: value, pagina: 1 })}>
    <SelectTrigger aria-label="Situação" className="sm:w-48">
      <SelectValue placeholder="Todas as situações" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="aberta">Aberta</SelectItem>
      <SelectItem value="paga">Paga</SelectItem>
      <SelectItem value="cancelada">Cancelada</SelectItem>
    </SelectContent>
  </Select>
</div>
<FilterBar filters={applied} onFiltersChange={(next) => setParams(paramsOf(next))} />
```

O `setParams` e o `paramsOf` são do projeto: escrevem e leem a URL pelo
roteador que ele usa.

## Texto

- O placeholder da busca diz por onde ela acha: "Número, cliente ou CNPJ", e
  não "Buscar…".
- O filtro aplicado diz o campo e o valor: "Situação: Aberta", e não só
  "Aberta".
- O botão do painel no celular diz quantos vai mostrar: "Ver 48 notas".
- O sem resultado diz o filtro e a saída: "Nenhuma nota aberta deste cliente.
  Limpar filtros".

## Acessibilidade

- A busca e cada filtro têm rótulo, mesmo quando o visível é só o placeholder:
  `aria-label` no campo, ou o `FieldLabel` escondido com `sr-only`.
- A contagem do resultado sai numa região viva educada ("48 notas"), para quem
  não vê a lista mudar.
- O xis de cada filtro aplicado nomeia o que remove ("Remover Situação:
  Aberta"): o `FilterBar` já faz.
- Filtrar não leva o foco embora do campo que a pessoa está usando.

## No celular e no nativo

No celular a busca fica no topo, os filtros num botão "Filtros (2)" que abre a
`Sheet`, e a fileira do `FilterBar` rola na horizontal logo abaixo, com o
limpar ancorado fora do que rola. No `@rivocode/ui-native` o `SearchInput` pede
`value` e `onValueChange`, o `FilterBar` traduz, e o estado vai nos parâmetros
da rota do router nativo, pela mesma razão da URL: voltar do detalhe devolve o
recorte.

A loja tem o seu jeito de filtrar, com contagem por opção e o carregar mais:
[comercio.md](https://ds.rivocode.com.br/skill/reference/comercio.md).

## Os blocos que o aplicam

- [Listagem de produtos](https://ds.rivocode.com.br/blocos#listagem)
