# TransferList

Duas listas lado a lado: à esquerda o que **está disponível**, à direita o que
**foi escolhido**. A pessoa marca um ou vários itens e os passa de um lado para
o outro. Permissões de um papel, colunas de um relatório, cidades de entrega,
os produtos de uma tabela de preço.

```tsx
const [granted, setGranted] = useState<string[]>([])

<TransferList
  items={[
    { value: 'pedidos.reembolsar', label: 'Reembolsar pedido' },
    { value: 'pedidos.cancelar', label: 'Cancelar pedido' },
    { value: 'conta.excluir', label: 'Excluir a conta', disabled: true },
  ]}
  value={granted}
  onValueChange={setGranted}
  labels={{ available: 'Permissões', chosen: 'Concedidas' }}
/>
```

A peça é controlada: `value` são os `value` dos escolhidos, e `onValueChange`
recebe a lista nova a cada movimento. O lado da direita aparece **na ordem do
`value`**, e o que entra vai para o fim, na ordem de `items`. O lado da esquerda
é `items` sem os escolhidos, na ordem de `items`.

## Mover

Entre as duas listas ficam quatro botões: mover os marcados para a direita,
mover todos para a direita, e os mesmos dois de volta. Cada um tem nome próprio
("Mover selecionados para Escolhidos") e a dica com o mesmo texto ao pousar o
ponteiro. O botão fica apagado quando não há o que mover.

"Mover todos" move **o que está à mostra**: com uma busca digitada, só o que a
busca deixou na lista. O marcado que a busca escondeu também não é movido pelo
"mover selecionados", para ninguém mover o que não está vendo.

Item com `disabled` não se marca e não se move, nem pelo "mover todos": ele
fica onde está. Serve para a permissão que o papel não pode perder ou ganhar.

Depois de mover, a frase "3 itens movidos para Escolhidos" é dita numa região
viva educada, com o plural certo e o nome da lista de destino. Se o botão
apertado apagou (porque não sobrou nada para mover), o foco passa para a lista
de destino, e não cai no começo da página.

## Estreita, empilha

Abaixo de 640px as duas listas empilham, e os botões de mover viram uma fileira
entre elas, com as setas apontando para baixo e para cima. A largura que conta é
a de quem contém a peça, e não a da janela: num painel lateral de 400px de uma
tela larga, ela empilha também. Antes da primeira medida, vale a janela.

## A contagem e a busca

O cabeçalho de cada lista diz quantos itens ela tem ("10 itens") e, com itens
marcados, quantos estão marcados ("3 de 10 selecionados"). A contagem é a
descrição da lista para o leitor de tela.

A busca no topo de cada lista ignora acento e caixa: "sao" acha "São Paulo" e
"joao" acha "João Pessoa". Sem resultado, a lista diz "Nada encontrado"; vazia,
diz "Nenhum item". `searchable={false}` tira as duas buscas, para listas curtas.

## Nome

A peça inteira é um grupo (`role="group"`), e o nome dele vem de `aria-label`
ou `aria-labelledby`: “Permissões do perfil”. Dentro de um `Field`, sem nenhum
dos dois, o grupo toma o nome do `FieldLabel`. Cada lista continua com o
próprio nome, o título dela.

## Teclado

Cada lista é uma parada de Tab e anda pelo padrão de lista com seleção
múltipla:

| Tecla | O que faz |
| --- | --- |
| Seta para cima e para baixo | anda pela lista sem marcar |
| Espaço | marca ou desmarca o item atual |
| Shift + seta | anda e marca o caminho |
| Home e End | vão ao primeiro e ao último; com Shift, marcam o trecho |
| Ctrl + A (⌘ + A) | marca tudo o que está à mostra, ou desmarca se já estava |
| Enter | move os marcados para a outra lista |
| Esc | desmarca tudo |

Na busca, a seta para baixo desce para a lista.

## Textos

`labels` troca os nomes das listas (`available` e `chosen`), as frases de
vazio (`empty` e `noResults`), o texto de espera da busca (`search`), a
contagem (`count`) e o anúncio (`moved`). Os
nomes dos botões e das buscas acompanham os nomes das listas.

## Partes

`classNames` alcança cada nó pelo nome: `panel` (cada lista com a moldura),
`header`, `search`, `list` (a caixa que rola, com 240px de altura), `option`,
`actions` (a coluna dos botões) e `empty`. A altura da lista se troca em
`classNames.list`.

No celular, as duas listas empilham, e as setas dos botões giram para apontar
para cima e para baixo.

## Quando não usar

- **Marcar algumas opções de uma lista curta** é `CheckboxGroup`. A
  `TransferList` vale quando a lista é longa e o que importa é ver, lado a lado,
  o que ficou de fora e o que entrou.
- **Escolher vários de uma lista longa sem precisar ver o que sobrou** é
  `Combobox` com `multiple`: ele ocupa uma linha só e mostra o escolhido em
  fichas.
- **Pôr os escolhidos numa ordem que só a pessoa sabe** é `SortableList`. A
  `TransferList` acrescenta no fim, e não arrasta.
- **Escolher dentro de uma árvore**, como departamentos e equipes, é
  `TreeSelect`.

## No React Native

Traduz, com os mesmos `items`, `value`, `onValueChange`, `searchable`, `disabled` e `labels`, e as mesmas frases de contagem e de anúncio.

**As listas empilham, e cada uma tem os próprios botões.** No telefone não há largura para duas colunas com botões no meio: a lista de cima é a de disponíveis, a de baixo a de escolhidos, e cada uma fecha com “Mover selecionados para …” e “Mover todos para …”. Cada linha é uma caixa de marcar com alvo de 44 pontos, e a lista rola por dentro a partir de 288 pontos. O anúncio sai pelo leitor de tela do sistema.

As partes vestem pelo mesmo `classNames` do web: `panel`, `header`, `search`, `list`, `option`, `actions` e `empty`. Como os botões moram em cada lista, `actions` veste a fileira embaixo de cada uma, e não uma coluna no meio.

## Importação

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

## Exemplos

### As permissões de um papel

```tsx
import { TransferList, type TransferListItem } from '@rivocode/ui'
import { useState } from 'react'

const PERMISSIONS: TransferListItem[] = [
  { value: 'pedidos.reembolsar', label: 'Reembolsar pedido' },
  { value: 'pedidos.cancelar', label: 'Cancelar pedido' },
  { value: 'produtos.editar', label: 'Editar produto' },
  { value: 'estoque.ajustar', label: 'Ajustar o estoque' },
  { value: 'relatorios.ver', label: 'Ver relatórios' },
  { value: 'relatorios.exportar', label: 'Exportar relatórios' },
  { value: 'usuarios.convidar', label: 'Convidar usuário' },
  { value: 'conta.excluir', label: 'Excluir a conta', disabled: true },
]

const CITIES: TransferListItem[] = [
  { value: 'sp', label: 'São Paulo' },
  { value: 'rj', label: 'Rio de Janeiro' },
  { value: 'bh', label: 'Belo Horizonte' },
  { value: 'jp', label: 'João Pessoa' },
  { value: 'rec', label: 'Recife' },
  { value: 'for', label: 'Fortaleza' },
  { value: 'poa', label: 'Porto Alegre' },
  { value: 'cwb', label: 'Curitiba' },
  { value: 'mao', label: 'Manaus' },
  { value: 'bel', label: 'Belém' },
]

export function Permissions() {
  const [granted, setGranted] = useState<string[]>(['relatorios.ver'])

  return (
    <TransferList
      items={PERMISSIONS}
      value={granted}
      onValueChange={setGranted}
      labels={{ available: 'Permissões', chosen: 'Concedidas' }}
      className="w-full"
    />
  )
}

const CITIES: TransferListItem[] = [
  { value: 'sp', label: 'São Paulo' },
  { value: 'rj', label: 'Rio de Janeiro' },
  { value: 'bh', label: 'Belo Horizonte' },
  { value: 'jp', label: 'João Pessoa' },
  { value: 'rec', label: 'Recife' },
  { value: 'for', label: 'Fortaleza' },
  { value: 'poa', label: 'Porto Alegre' },
  { value: 'cwb', label: 'Curitiba' },
  { value: 'mao', label: 'Manaus' },
  { value: 'bel', label: 'Belém' },
]
```

### Cidades de entrega, com busca sem acento

```tsx
import { TransferList, type TransferListItem } from '@rivocode/ui'
import { useState } from 'react'

const CITIES: TransferListItem[] = [
  { value: 'sp', label: 'São Paulo' },
  { value: 'rj', label: 'Rio de Janeiro' },
  { value: 'bh', label: 'Belo Horizonte' },
  { value: 'jp', label: 'João Pessoa' },
  { value: 'rec', label: 'Recife' },
  { value: 'for', label: 'Fortaleza' },
  { value: 'poa', label: 'Porto Alegre' },
  { value: 'cwb', label: 'Curitiba' },
  { value: 'mao', label: 'Manaus' },
  { value: 'bel', label: 'Belém' },
]

export function Cities() {
  const [cities, setCities] = useState<string[]>([])

  return (
    <TransferList items={CITIES} value={cities} onValueChange={setCities} className="w-full" />
  )
}
```

### Desabilitada

```tsx
import { TransferList, type TransferListItem } from '@rivocode/ui'
import { useState } from 'react'

const CITIES: TransferListItem[] = [
  { value: 'sp', label: 'São Paulo' },
  { value: 'rj', label: 'Rio de Janeiro' },
  { value: 'bh', label: 'Belo Horizonte' },
  { value: 'jp', label: 'João Pessoa' },
  { value: 'rec', label: 'Recife' },
  { value: 'for', label: 'Fortaleza' },
  { value: 'poa', label: 'Porto Alegre' },
  { value: 'cwb', label: 'Curitiba' },
  { value: 'mao', label: 'Manaus' },
  { value: 'bel', label: 'Belém' },
]

export function Disabled() {
  return (
    <TransferList
      items={CITIES.slice(0, 4)}
      value={['jp']}
      onValueChange={() => {}}
      disabled
      searchable={false}
      className="w-full"
    />
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `items` | `TransferListItem[]` | sim |  | - | Todos os itens, dos dois lados. |
| `onValueChange` | `(value: string[]) => void` | sim |  | - | Recebe o `value` novo a cada movimento. |
| `value` | `string[]` | sim |  | - | Os `value` dos escolhidos, na ordem em que aparecem na lista da direita. |
| `classNames` | `Partial<Record<"actions" \| "empty" \| "header" \| "list" \| "option" \| "panel" \| "search", string>>` |  |  | - | Classe por parte: `panel` (cada lista com a moldura), `header`, `search`, `list` (a caixa que rola), `option`, `actions` (a coluna dos botoes) e `empty`. |
| `disabled` | `boolean` |  | `false` | - | Desliga as duas listas, as buscas e os botoes de mover. |
| `labels` | `TransferListLabels` |  |  | - | Os textos da peca, para trocar o nome das listas ou o anuncio. |
| `searchable` | `boolean` |  | `true` | - | Liga a busca no topo de cada lista, sem acento importar. |

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

## Ver também

- [AudioRecorder](/componentes/audio-recorder.md)
- [Autocomplete](/componentes/autocomplete.md)
- [Calendar](/componentes/calendar.md)
- [Checkbox](/componentes/checkbox.md)
- [CheckboxCard](/componentes/checkbox-card.md)
- [CheckboxGroup](/componentes/checkbox-group.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
