# Ações em lote

Marcar vários itens e agir em todos de uma vez: a seleção diz quantos são e de
onde, a barra diz o que dá para fazer, e o que se faz em lote se desfaz em lote.

## O problema

Arquivar quarenta pedidos um a um é a tarefa que faz a pessoa pedir uma
planilha. E a seleção mal feita é pior que nenhuma: o "selecionar todos" que
marca só a página visível e exporta vinte quando a pessoa queria os trezentos;
o botão de excluir da linha que continua vivo no meio de uma seleção e apaga só
aquela; a ação em lote que não se desfaz e leva cem registros num clique.

## Quando usar

Listagens de operação em que a mesma ação se repete sobre muitos itens:
exportar, arquivar, reenviar, mudar a situação, atribuir a alguém, excluir. A
seleção vale a coluna de checkbox quando a pessoa faz isso toda semana.

## Quando não usar

- **Lista curta, de menos de uma dúzia**, em que a ação mais comum é sobre um
  item: o menu da linha basta.
- **Escolher itens para outra tela** (os produtos de um pedido, os
  participantes de uma reunião) não é ação em lote: é `TransferList`,
  `Combobox` com `multiple` ou `CheckboxGroup`.
- **Feed e catálogo de loja** não têm seleção: a pessoa age sobre um de cada
  vez.

## As peças

- `DataTable` com `selectable`, `value` e `onValueChange`: a coluna de
  checkbox, com o do cabeçalho em três estados.
- `Checkbox` com `indeterminate`: o cabeçalho montado à mão, fora do
  `DataTable`.
- `ActionBar` com `count` e `onClear`: a barra das ações, que aparece com a
  seleção e diz quantos.
- `useToast` com `actionProps`: o desfazer do lote.
- `AlertDialog`: a confirmação do lote que não se desfaz.
- `Progress`: o lote longo, com o quanto.

## Comportamento

### O checkbox do cabeçalho tem três estados

Desmarcado quando nada está marcado, misto (`indeterminate`) quando parte da
página está, marcado quando a página inteira está. O clique no misto marca
todos da página, e o clique no marcado desmarca. O `DataTable` com `selectable`
já faz assim: **o cabeçalho marca a página visível, e não a lista inteira.**

### Selecionar todos os N, entre páginas

Marcada a página inteira, uma linha acima da tabela oferece o resto: "Os 25
desta página estão selecionados. Selecionar as 248 notas". Escolhido, ela troca
para "As 248 notas estão selecionadas. Limpar seleção". A ação passa a valer
para o filtro inteiro, e não para uma lista de chaves: o servidor recebe o
filtro, porque as 248 não estão todas na tela.

```tsx
const [selected, setSelected] = useState<string[]>([])
const [allMatching, setAllMatching] = useState(false)
const pageFull = selected.length === invoices.data?.items.length
const count = allMatching ? (invoices.data?.total ?? 0) : selected.length

{pageFull && !allMatching && (
  <Text size="sm">
    {`Os ${selected.length} desta página estão selecionados. `}
    <Link render={<button type="button" />} onClick={() => setAllMatching(true)}>
      {`Selecionar as ${invoices.data?.total} notas`}
    </Link>
  </Text>
)}

<DataTable
  data={invoices.data?.items}
  rowCount={invoices.data?.total ?? 0}
  columns={COLUMNS}
  rowKey={(invoice) => invoice.id}
  selectable
  value={selected}
  onValueChange={(keys) => {
    setAllMatching(false)
    setSelected(keys)
  }}
/>

<ActionBar
  count={count}
  onClear={() => {
    setAllMatching(false)
    setSelected([])
  }}
>
  <Button size="sm" variant="secondary" onClick={() => exportInvoices(allMatching ? { filters } : { ids: selected })}>
    Exportar notas
  </Button>
</ActionBar>
```

- **Trocar de filtro limpa a seleção.** O que estava marcado pode não estar
  mais na lista, e agir sobre o invisível é o pior erro deste padrão.
- **Trocar de página mantém a seleção**, e a contagem da barra continua
  somando: a pessoa marca três na primeira e dois na segunda.

### As ações da linha ficam desabilitadas no lote

Com algum item marcado, o menu e os botões de cada linha ficam desabilitados, e
a ação acontece pela `ActionBar`. Senão a pessoa marca dez, clica no "Excluir"
da linha onze, e não sabe se apagou um ou onze. Sem nada marcado, a linha volta
a agir sozinha.

### A barra

A `ActionBar` aparece quando há seleção, gruda no pé da área, diz "12
selecionados" e oferece só o que vale para todos. A ação que não vale para algum
item marcado (reenviar uma nota cancelada) não some: faz nos que valem e diz
quantos ficaram de fora.

### Desfazer em lote

O que se faz em lote se desfaz em lote, num aviso só: "12 notas arquivadas.
Desfazer". O desfazer devolve os doze, e não o último. O lote sem volta (excluir
de vez, emitir) confirma com o número no título: "Excluir 12 rascunhos?", e acima
de um limite que o produto decide, pede para digitar a quantidade
([verbos-de-acao.md](https://ds.rivocode.com.br/padroes/verbos-de-acao.md)).

O lote que passa de dez segundos mostra o progresso, com o que já foi e o que
falhou: "128 de 400 notas reenviadas. 3 falharam", com o "Ver as que falharam"
no fim ([espera.md](https://ds.rivocode.com.br/padroes/espera.md)).

## Texto

- A barra diz o número e o objeto: "12 notas selecionadas", com
  `labels.selected` para acertar o gênero.
- As ações da barra são verbo e objeto no plural: "Exportar notas", "Arquivar
  pedidos".
- O desfazer e a confirmação repetem o número: "12 notas arquivadas", "Excluir
  12 rascunhos?".
- O "selecionar todos" diz quantos de verdade: "Selecionar as 248 notas", e não
  "Selecionar tudo".

## Acessibilidade

- O checkbox do cabeçalho tem nome ("Selecionar todas as linhas da página", em
  `labels.selectAll`) e anuncia o estado misto como `mixed`.
- A `ActionBar` anuncia a contagem numa região viva educada, e "Seleção limpa"
  quando zera. Ela não leva o foco: a pessoa continua marcando.
- Na tabela, o leitor de tela lê a caixa da linha junto com as células dela.
  Fora da tabela, numa lista montada à mão, cada caixa nomeia o item
  ("Selecionar a nota 4813"), e não "Selecionar" repetido.
- A barra fixa no pé da janela não pode cobrir o foco: com `position="fixed"`,
  reserve a altura dela na rolagem.

## No celular e no nativo

No celular a seleção entra por um modo: "Selecionar" no cabeçalho da lista, ou
o toque longo num item, e a lista ganha as caixas. O `DataList` do
`@rivocode/ui-native` porta o `selectable` com `value` e `onValueChange`, o
toque longo é o `onRowLongPress`, e `labels.selectRow` aceita a função da linha
para cada caixa nomear o item; o
`Checkbox` nativo tem `indeterminate`, e a caixa de selecionar todas se monta à
mão. A `ActionBar` nativa gruda acima da área segura de baixo, pelo
`bottomInset`.

## Os blocos que o aplicam

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