# ActionBar

A barra das ações **em lote**: aparece quando há itens selecionados, diz
quantos são, oferece o que dá para fazer com todos eles de uma vez e deixa
limpar a seleção. Exportar vinte pedidos, desmarcar três consultas, reenviar os
recibos de uma semana.

```tsx
const [selected, setSelected] = useState<string[]>([])

<DataTable
  data={appointments}
  columns={columns}
  rowKey={(appointment) => appointment.id}
  selectable
  value={selected}
  onValueChange={setSelected}
/>
<ActionBar count={selected.length} onClear={() => setSelected([])}>
  <Button size="sm" variant="secondary">Exportar agenda</Button>
  <Button size="sm" variant="danger">Desmarcar consultas</Button>
</ActionBar>
```

A barra não guarda estado nenhum. `count` diz quantos estão marcados, e é o
`length` do `value` do `DataTable`; `onClear` é quem zera a seleção. Com o
`DataTable` controlado, o "Limpar seleção" desmarca a tabela na mesma hora,
porque os dois leem o mesmo estado.

## Quando aparece

Acima de zero ela entra, subindo do pé da área; em zero ela sai. A entrada usa
a curva de entrada dos tokens de movimento (`--rc-ease-enter`, na duração
`base`) e a saída usa a de saída (`--rc-ease-exit`, na `fast`), então quem pediu
ao sistema para reduzir movimento vê a barra aparecer e sumir sem deslize.

Enquanto sai, ela continua dizendo o último número (e não "0 selecionados") até
terminar de sumir. Fechada, ela fica inerte: nenhum botão dela recebe foco nem
clique.

## A contagem, dita em voz alta

A frase sai no plural certo e com o número no formato brasileiro: "1
selecionado", "3 selecionados", "1.234 selecionados". Ela é também anunciada
numa região viva educada, que existe antes da primeira seleção (região montada
junto com o texto não é anunciada por leitor de tela nenhum). Quando a seleção
zera, o que se ouve é "Seleção limpa".

`labels.selected` recebe a contagem e devolve a frase, para quem quer dar nome
ao item e acertar o gênero:

```tsx
<ActionBar
  count={selected.length}
  onClear={() => setSelected([])}
  labels={{
    selected: (count) => (count === 1 ? '1 consulta selecionada' : `${count} consultas selecionadas`),
  }}
>
  <Button size="sm" variant="secondary">Reenviar por e-mail</Button>
</ActionBar>
```

## Onde ela gruda

`position="sticky"`, o padrão, gruda no pé da área que a contém: ponha a barra
logo depois da tabela, dentro do mesmo bloco. Enquanto está aberta ela ocupa
lugar embaixo da tabela, então a paginação nunca fica escondida atrás dela.

`position="fixed"` gruda no pé da janela, acima da área segura do celular, e não
ocupa lugar nenhum. É para listagem que ocupa a tela inteira; numa tela com
mais de uma área, a `sticky` diz melhor de qual lista ela fala.

Como a `fixed` não ocupa lugar, ela pode cobrir o controle que recebe o foco
pelo Tab no pé da tela, e o navegador não rola para tirá-lo de baixo dela.
Reserve a altura da barra na rolagem da página enquanto ela está aberta:

```css
html {
  scroll-padding-bottom: 6rem;
}
```

Com Tailwind é a classe `scroll-pb-24` no `html`. Se a página rola dentro de um
contêiner, a regra vai nele, e não no `html`. Os `6rem` cobrem a barra de uma
linha com a área segura; com ações que quebram em duas linhas no celular, suba
o valor.

Os botões dentro dela quebram o rótulo longo em mais de uma linha em vez de
empurrar a página para o lado, então a barra cabe em 320px, que é a tela de
quem usa zoom de 400%.

Nos dois casos ela empilha em `--rc-z-sticky`: fica acima do conteúdo que rola
e abaixo de menu, diálogo e aviso.

## O foco

Quando a barra sai com o foco dentro dela (depois do "Limpar seleção", ou de
uma ação que zera a seleção), o foco não cai no começo da página: ele volta
para onde estava antes de entrar na barra, que quase sempre é o checkbox da
última linha marcada. Se aquilo sumiu da tela, ele fica na raiz da barra, no
mesmo ponto da leitura. `finalFocus` manda para outro lugar, como o bloco da
tabela. Foco que estava fora da barra não é tocado.

## Partes

`classNames` alcança cada nó pelo nome: `bar` (o painel), `count`, `actions` e
`clear`.

## Quando não usar

- **Ação de uma linha só** mora na própria linha, num `Menu` da coluna de
  ações. A `ActionBar` é para o que se faz com vários de uma vez; com um item só
  ela aparece, mas quem clicou na linha esperava a ação ali.
- **Controles que ficam sempre na tela**, como filtro, busca e exportar tudo,
  são `Toolbar`. A `Toolbar` está lá desde o começo e anda por seta; a
  `ActionBar` só existe enquanto há seleção.
- **Confirmar o que a ação fez** é `Toast`. A barra não diz "3 consultas
  desmarcadas": quem chamou limpa a seleção, a barra sai, e o `Toast` conta o
  resultado.
- **Salvar o que mudou num formulário** é `SaveBar`, que entra pelo mesmo
  lugar mas fala de mudança pendente, e não de seleção.
- **Ação destrutiva em lote** não roda direto do botão da barra: ela abre um
  `AlertDialog` dizendo quantos itens vão embora.

## No React Native

Traduz, com o mesmo `count`, o mesmo `onClear` e a mesma frase no plural certo. As ações entram como filhas, e o texto dos botões é o do `Button` nativo.

**Ela gruda acima da área segura de baixo.** O pacote não depende do `react-native-safe-area-context`, então a altura da barra do sistema entra por `bottomInset`: `bottomInset={useSafeAreaInsets().bottom}`. A barra fica por cima da lista, em `absolute`, e quem a monta deixa o respiro no fim da lista para a última linha não ficar embaixo dela.

**A contagem é anunciada.** A frase sai pelo anúncio do leitor de tela do sistema, e a barra entra subindo e sai descendo com os tokens de movimento, sem deslize quando o sistema pede para reduzir movimento.

As partes vestem pelo mesmo `classNames` do web: `bar`, `count` e `clear`, e o `className` veste o mesmo painel de `bar`. `actions` não existe aqui: as ações são filhas diretas do painel, sem caixa própria.

## Importação

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

## Exemplos

### Com a seleção do DataTable

```tsx
import { ActionBar, Button, DataTable, type Column } from '@rivocode/ui'
import { Download, Trash2 } from 'lucide-react'
import { useRef, useState } from 'react'

type Appointment = {
  id: string
  time: string
  patient: string
  doctor: string
}

const APPOINTMENTS: Appointment[] = [
  { id: '1', time: '08:00', patient: 'Lúcia Fontes', doctor: 'Dra. Paula Reis' },
  { id: '2', time: '08:30', patient: 'Marcos Teixeira', doctor: 'Dr. Henrique Lobo' },
  { id: '3', time: '09:00', patient: 'Gabriela Moura', doctor: 'Dra. Paula Reis' },
  { id: '4', time: '09:30', patient: 'Tomás Rezende', doctor: 'Dr. Henrique Lobo' },
  { id: '5', time: '10:00', patient: 'Isadora Campos', doctor: 'Dra. Paula Reis' },
]

const COLUMNS: Column<Appointment>[] = [
  { key: 'time', header: 'Horário' },
  { key: 'patient', header: 'Paciente' },
  { key: 'doctor', header: 'Profissional' },
]

export function WithDataTable() {
  const [selected, setSelected] = useState<string[]>(['2', '3'])

  return (
    <div className="flex w-full flex-col gap-3">
      <DataTable
        data={APPOINTMENTS}
        columns={COLUMNS}
        rowKey={(appointment) => appointment.id}
        selectable
        value={selected}
        onValueChange={setSelected}
      />
      <ActionBar count={selected.length} onClear={() => setSelected([])}>
        <Button size="sm" variant="secondary">
          <Download aria-hidden="true" size={14} />
          Exportar agenda
        </Button>
        <Button size="sm" variant="danger">
          <Trash2 aria-hidden="true" size={14} />
          Desmarcar consultas
        </Button>
      </ActionBar>
    </div>
  )
}
```

### Com o nome do item

```tsx
import { ActionBar, Button, DataTable, type Column } from '@rivocode/ui'
import { Download, Trash2 } from 'lucide-react'
import { useRef, useState } from 'react'

type Appointment = {
  id: string
  time: string
  patient: string
  doctor: string
}

const APPOINTMENTS: Appointment[] = [
  { id: '1', time: '08:00', patient: 'Lúcia Fontes', doctor: 'Dra. Paula Reis' },
  { id: '2', time: '08:30', patient: 'Marcos Teixeira', doctor: 'Dr. Henrique Lobo' },
  { id: '3', time: '09:00', patient: 'Gabriela Moura', doctor: 'Dra. Paula Reis' },
  { id: '4', time: '09:30', patient: 'Tomás Rezende', doctor: 'Dr. Henrique Lobo' },
  { id: '5', time: '10:00', patient: 'Isadora Campos', doctor: 'Dra. Paula Reis' },
]

const COLUMNS: Column<Appointment>[] = [
  { key: 'time', header: 'Horário' },
  { key: 'patient', header: 'Paciente' },
  { key: 'doctor', header: 'Profissional' },
]

export function NamedItems() {
  const [selected, setSelected] = useState<string[]>(['1'])
  const table = useRef<HTMLDivElement>(null)

  return (
    <div ref={table} tabIndex={-1} className="flex w-full flex-col gap-3 rounded-lg focus-visible:outline-hidden focus-visible:ring-focus focus-visible:ring-ring">
      <DataTable
        data={APPOINTMENTS}
        columns={COLUMNS}
        rowKey={(appointment) => appointment.id}
        selectable
        value={selected}
        onValueChange={setSelected}
      />
      <ActionBar
        count={selected.length}
        onClear={() => setSelected([])}
        finalFocus={table}
        labels={{
          selected: (count) =>
            count === 1 ? '1 consulta selecionada' : `${count} consultas selecionadas`,
        }}
      >
        <Button size="sm" variant="secondary">
          Enviar lembrete
        </Button>
      </ActionBar>
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `count` | `number` | sim |  | - | Quantos itens estao selecionados. |
| `classNames` | `Partial<Record<"actions" \| "bar" \| "clear" \| "count", string>>` |  |  | - | Classe por parte: `bar` (o painel), `count`, `actions` e `clear`. |
| `finalFocus` | `RefObject<HTMLElement \| null>` |  |  | - | Para onde o foco vai quando a barra sai com ele dentro - depois do "Limpar seleção", ou de uma acao que zera a selecao. |
| `labels` | `{ selected?: ((count: number) => string) \| undefined; clear?: string \| undefined; region?: string \| undefined; cleared?: string \| undefined; }` |  |  | - | Os textos da barra. |
| `onClear` | `(() => void)` |  |  | - | Liga o "Limpar seleção" no fim da barra. |
| `position` | `"fixed" \| "sticky"` |  | `"sticky"` | - | `sticky` gruda no pe da area que a contem e ocupa lugar embaixo dela enquanto esta aberta; `fixed` gruda no pe da janela, acima da area segura do celular, e nao ocupa lugar nenhum. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [Button](/componentes/button.md)
- [ButtonGroup](/componentes/button-group.md)
- [Clipboard](/componentes/clipboard.md)
- [IconButton](/componentes/icon-button.md)
- [ScrollToTop](/componentes/scroll-to-top.md)
- [Toggle](/componentes/toggle.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
