# SortableList

A lista que a pessoa põe em ordem com as próprias mãos: a prioridade das
tarefas do time, as etapas de um processo, a ordem das aulas de um curso. Arrasta com o
ponteiro, com o dedo e com o teclado, e o leitor de tela ouve cada passo. Vive
em `@rivocode/ui/dnd`, atrás do `@dnd-kit/core` e do `@dnd-kit/sortable`, que
são dependências opcionais: só quem importa este caminho as instala.

```bash
npm install @dnd-kit/core @dnd-kit/sortable
```

```tsx
import { SortableList } from '@rivocode/ui/dnd'

const [tasks, setTasks] = useState(initialTasks)

<SortableList
  aria-label="Ordem de prioridade"
  items={tasks}
  getKey={(task) => task.id}
  getLabel={(task) => `Tarefa ${task.number}`}
  onReorder={setTasks}
  renderItem={(task) => (
    <Item>
      <ItemContent>
        <ItemTitle>{task.title}</ItemTitle>
        <ItemDescription>Prazo {task.due}</ItemDescription>
      </ItemContent>
    </Item>
  )}
/>
```

## A peça é controlada

`items` entra, a ordem nova sai pronta em `onReorder(items, { key, from, to })`,
e a peça desenha o que voltar. Ela não guarda ordem nenhuma sozinha: sem o pai
trocar `items`, o item volta para o lugar ao ser solto. É isso que deixa a
ordem ir ao servidor antes de mudar na tela, e voltar atrás se ele recusar.

Soltar no mesmo lugar e cancelar com Esc não chamam `onReorder`.

`getKey` é a identidade do item, e tem que ser única e estável: a chave que
anda com o item, e não a posição dele.

## Teclado e leitor de tela

O teclado não é uma alternativa de segunda: é o caminho de quem não usa mouse.

| Tecla | O que faz |
| --- | --- |
| Espaço ou Enter | pega o item com o foco na alça |
| Setas | movem o item uma posição |
| Espaço ou Enter | solta no lugar novo |
| Esc | cancela, e o item volta para onde estava |

Cada passo é anunciado numa região viva, com o nome que `getLabel` devolve:
"Item Tarefa 213 pego. Posição 2 de 8.", "Item Tarefa 213 movido para a
posição 3 de 8.", "Item Tarefa 213 solto na posição 3 de 8.". A alça se chama
"Reordenar Tarefa 213", e a instrução de teclado fica ligada a ela por
`aria-describedby`, para o leitor ler ao chegar e não a cada passo.

`labels` troca qualquer um desses textos, inclusive a palavra "Item", quando a
lista é de outra coisa:

```tsx
<SortableList
  items={steps}
  getKey={(step) => step.id}
  getLabel={(step) => step.name}
  onReorder={setSteps}
  labels={{
    moved: (label, position, total) => `Etapa ${label} agora é a ${position}ª de ${total}.`,
  }}
  renderItem={(step) => step.name}
/>
```

## Mover sem arrastar

Arrastar não pode ser o único caminho: a WCAG 2.5.7 pede um jeito de ponteiro
único, sem segurar, para quem usa um dedo só, o mouse sem prender o botão ou o
controle por voz. E o teclado sozinho não cumpre esse pedido.

Por isso cada item traz, no fim da linha, o botão **"Mover Tarefa 213"**, que
abre um `Menu` com **Para o início**, **Para cima**, **Para baixo** e **Para o
fim**. O menu mostra só o que anda: o primeiro item não tem subida, e o
segundo não repete "Para o início" ao lado de "Para cima". Escolher chama o
mesmo `onReorder(items, { key, from, to })` do arrasto, anuncia "Item Tarefa
213 movido para a posição 1 de 8." e devolve o foco ao botão do item no
lugar novo, para o próximo passo sair dali.

O botão vem ligado, com ou sem `handle`. Ele mora fora da alça e fora do
`renderItem`, então a linha toda que recebe `handleProps` continua sendo um
controle só. Na horizontal os passos se chamam **Para a esquerda** e **Para a
direita**. Some quando a lista está `disabled` ou tem um item só, e
`moveMenu={false}` o desliga quando a tela já dá outro caminho (um campo de
posição, por exemplo). Os textos trocam por `labels`: `move`, `first`,
`earlier`, `later` e `last`.

## A alça

`handle`, ligado por padrão, desenha um `IconButton` com o ícone de pegar no
início de cada linha, e **só ele arrasta**. O resto da linha continua
clicável, selecionável e, no celular, rolável: é a alça que trava a rolagem
enquanto o dedo está nela, e não a linha inteira.

Com `handle={false}` a peça não desenha alça, e quem arrasta é o elemento onde
você espalhar `handleProps`: a sua própria alça, ou a linha toda. Nesse modo o
toque pede para **segurar** o item antes de ele sair do lugar, e deslizar sem
segurar continua rolando a tela.

```tsx
<SortableList
  items={tasks}
  getKey={(task) => task.id}
  onReorder={setTasks}
  handle={false}
  renderItem={(task, { handleProps, isDragging }) => (
    <div {...handleProps} className={isDragging ? 'shadow-2' : undefined}>
      {task.title}
    </div>
  )}
/>
```

## Horizontal

`orientation="horizontal"` vira uma fileira que rola de lado quando não cabe, e
as setas que andam passam a ser esquerda e direita.

## Movimento

Os vizinhos abrem espaço com a mola espacial dos tokens
(`--rc-duration-spatial` e `--rc-ease-spatial`), e o item arrastado sobe com
`shadow-2`. Com "reduzir movimento" ligado no sistema a duração dos tokens vai a
zero: os vizinhos trocam de lugar sem deslizar, e a rolagem que o teclado
provoca ao chegar à borda também deixa de ser suave.

## Estados

- **Vazia**: a lista monta sem nenhum item e sem alça. Diga o que falta com um
  `EmptyState` no lugar dela.
- **`disabled`**: a alça sai desabilitada e nada arrasta, nem pelo teclado. Use
  enquanto a ordem anterior ainda está sendo salva.

## Partes

`classNames` alcança `item` (o `li` que anda), `handle` (a alça) e `content`
(a caixa em volta do que `renderItem` desenha).

## Quando não usar

- **Ordem por critério é `DataTable`.** Se a pessoa quer ver as tarefas por prazo
  ou por responsável, a coluna `sortable` resolve com um clique e sem ninguém mexer
  em nada. A `SortableList` é para a ordem que só a pessoa sabe, e que não
  sai de campo nenhum.
- **Mudar de grupo é `Kanban`.** Quando o item muda de situação ("A fazer"
  para "Em andamento") e não só de posição, as colunas são a informação, e o quadro
  mostra as duas coisas.
- **Hierarquia é `Tree`.** Pôr um item dentro de outro não é reordenar.

## No React Native

Traduz, no caminho próprio `@rivocode/ui-native/dnd`, com os mesmos `items`, `getKey`, `renderItem`, `onReorder`, `getLabel`, `handle`, `orientation`, `disabled`, `moveMenu` e `labels`.

**Sem peer novo.** O gesto é o `PanResponder` do React Native, o mesmo do `Slider`, e não o react-native-gesture-handler: arrastar pela alça, num eixo só, é um gesto que o core resolve sozinho. A alça tem 44pt e segura o gesto até o dedo sair (ela não cede à rolagem da tela no meio do arrasto), e o resto da linha continua rolando a lista, como na alça de reordenar do iOS. Por isso, no celular, **só a alça arrasta**: com a linha inteira como alça, todo toque para rolar viraria um arrasto.

**O leitor de tela não arrasta: ele move.** Cada alça traz duas ações, "Mover para cima" e "Mover para baixo" (ou esquerda e direita, na horizontal), e cada uma anda um passo e anuncia a posição nova com o mesmo texto do web: "Item Tarefa 1043 movido para a posição 3 de 8". O arrasto também anuncia ao pegar, a cada posição e ao soltar.

**Quem não arrasta, nem usa leitor de tela, toca em "Mover".** O botão de 44pt no fim de cada item abre uma `Sheet` com o início, um passo para cada lado e o fim, só o que anda, e escolher chama o mesmo `onReorder` e anuncia a posição nova. É o `moveMenu` do web, ligado de saída. Aqui as ações dizem "Mover para o início", "Mover para cima" e assim por diante, as mesmas palavras das ações do leitor de tela.

Durante o arrasto uma cópia do item segue o dedo por cima da lista, e os vizinhos abrem espaço com a duração `base` dos tokens, sem movimento quando o sistema pede para reduzir. `handleProps` são o gesto e as ações, para espalhar numa `View` sua com `handle={false}`.

## Importação

```tsx
import { SortableList } from '@rivocode/ui/dnd'
```

## Exemplos

### A fila de prioridades

```tsx
import { Badge, Item, ItemActions, ItemContent, ItemDescription, ItemTitle } from '@rivocode/ui'
import { SortableList } from '@rivocode/ui/dnd'
import { useState } from 'react'

type Task = { id: number; number: string; title: string; owner: string; estimate: string; due: string }

const QUEUE: Task[] = [
  { id: 1, number: '211', title: 'Corrigir o login pelo celular', owner: 'Bruna', estimate: '3 h', due: '26/09' },
  { id: 2, number: '212', title: 'Atualizar a página de preços', owner: 'Caio', estimate: '1 h', due: '27/09' },
  { id: 3, number: '213', title: 'Responder o chamado da Vila Verde', owner: 'Denise', estimate: '30 min', due: '30/09' },
  { id: 4, number: '214', title: 'Migrar o banco de testes', owner: 'Otávio', estimate: '1 dia', due: '02/10' },
  { id: 5, number: '215', title: 'Preparar a demonstração de outubro', owner: 'Bruna', estimate: '4 h', due: '05/10' },
]

const STAGES = ['Separar o pedido', 'Embalar', 'Gerar a etiqueta de frete', 'Entregar à transportadora']

export function IssueQueue() {
  const [tasks, setTasks] = useState(QUEUE)

  return (
    <div className="w-full max-w-lg">
      <SortableList
        aria-label="Ordem de prioridade"
        items={tasks}
        getKey={(task) => task.id}
        getLabel={(task) => `Tarefa ${task.number}`}
        onReorder={setTasks}
        renderItem={(task, { index }) => (
          <Item variant="outline">
            <ItemContent>
              <ItemTitle>{task.title}</ItemTitle>
              <ItemDescription>
                Tarefa {task.number} · {task.owner} · prazo {task.due}
              </ItemDescription>
            </ItemContent>
            <ItemActions>
              <span className="text-sm tabular-nums text-fg">{task.estimate}</span>
              {index === 0 && (
                <Badge tone="accent" size="sm">
                  Próxima
                </Badge>
              )}
            </ItemActions>
          </Item>
        )}
      />
    </div>
  )
}

const STAGES = ['Separar o pedido', 'Embalar', 'Gerar a etiqueta de frete', 'Entregar à transportadora']
```

### Horizontal, com a linha inteira como alça

```tsx
import { Badge, Item, ItemActions, ItemContent, ItemDescription, ItemTitle } from '@rivocode/ui'
import { SortableList } from '@rivocode/ui/dnd'
import { useState } from 'react'

const STAGES = ['Separar o pedido', 'Embalar', 'Gerar a etiqueta de frete', 'Entregar à transportadora']

export function Stages() {
  const [stages, setStages] = useState(STAGES)

  return (
    <div className="w-full max-w-2xl">
      <SortableList
        aria-label="Etapas do despacho"
        orientation="horizontal"
        handle={false}
        items={stages}
        getKey={(stage) => stage}
        getLabel={(stage) => stage}
        onReorder={setStages}
        labels={{
          handle: (label) => `Mover a etapa ${label}`,
          moved: (label, position, total) => `Etapa ${label} agora é a ${position}ª de ${total}.`,
        }}
        renderItem={(stage, { handleProps, isDragging, index }) => (
          <div
            {...handleProps}
            className={
              'flex cursor-grab items-center gap-2 rounded-md border border-border bg-surface ' +
              'px-3 py-2 text-sm text-fg focus-visible:outline-hidden focus-visible:ring-focus focus-visible:ring-ring ' +
              (isDragging ? 'shadow-2' : '')
            }
          >
            <span className="tabular-nums text-xs text-fg-muted">{index + 1}</span>
            {stage}
          </div>
        )}
      />
    </div>
  )
}
```

### Desabilitada enquanto salva

```tsx
import { Badge, Item, ItemActions, ItemContent, ItemDescription, ItemTitle } from '@rivocode/ui'
import { SortableList } from '@rivocode/ui/dnd'
import { useState } from 'react'

type Task = { id: number; number: string; title: string; owner: string; estimate: string; due: string }

const QUEUE: Task[] = [
  { id: 1, number: '211', title: 'Corrigir o login pelo celular', owner: 'Bruna', estimate: '3 h', due: '26/09' },
  { id: 2, number: '212', title: 'Atualizar a página de preços', owner: 'Caio', estimate: '1 h', due: '27/09' },
  { id: 3, number: '213', title: 'Responder o chamado da Vila Verde', owner: 'Denise', estimate: '30 min', due: '30/09' },
  { id: 4, number: '214', title: 'Migrar o banco de testes', owner: 'Otávio', estimate: '1 dia', due: '02/10' },
  { id: 5, number: '215', title: 'Preparar a demonstração de outubro', owner: 'Bruna', estimate: '4 h', due: '05/10' },
]

export function Saving() {
  return (
    <div className="w-full max-w-lg">
      <SortableList
        aria-label="Ordem de prioridade"
        disabled
        items={QUEUE.slice(0, 3)}
        getKey={(task) => task.id}
        getLabel={(task) => `Tarefa ${task.number}`}
        onReorder={() => {}}
        renderItem={(task) => (
          <Item variant="outline">
            <ItemContent>
              <ItemTitle>{task.title}</ItemTitle>
            </ItemContent>
          </Item>
        )}
      />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `getKey` | `(item: Item) => UniqueIdentifier` | sim |  | - | A identidade de cada item. |
| `items` | `readonly Item[]` | sim |  | - | Os itens, na ordem de agora. |
| `onReorder` | `(items: Item[], move: SortableListMove) => void` | sim |  | - | A ordem nova, ja montada, ao soltar num lugar diferente de onde o item saiu. |
| `renderItem` | `(item: Item, state: SortableItemState) => ReactNode` | sim |  | - | O desenho de cada item. |
| `classNames` | `Partial<Record<"content" \| "handle" \| "item", string>>` |  |  | - |  |
| `disabled` | `boolean` |  | `false` | - | Trava o arrasto inteiro, e a alca sai desabilitada. |
| `getLabel` | `((item: Item) => string)` |  |  | - | O nome do item nos anuncios e no nome da alca: "Pedido 1043" vira "Item Pedido 1043 movido para a posicao 3 de 8". |
| `handle` | `boolean` |  | `true` | - | Desenha a alca, um `IconButton` com o icone de pegar, no inicio de cada item, e so ela arrasta. |
| `labels` | `Partial<SortableListLabels>` |  |  | - | Os textos dos anuncios, da instrucao, do nome da alca e do menu de mover (`move`, `first`, `earlier`, `later`, `last`), para outra lingua ou outro nome de coisa ("Etapa" em vez de "Item"). |
| `moveMenu` | `boolean` |  | `true` | - | O botao "Mover" no fim de cada item, que abre um menu com o inicio, um passo para cada lado e o fim. |
| `orientation` | `"horizontal" \| "vertical"` |  | `"vertical"` | - | O eixo da lista. |

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

## Ver também

- [AudioPlayer](/componentes/audio-player.md)
- [Code](/componentes/code.md)
- [EventCalendar](/componentes/event-calendar.md)
- [Gantt](/componentes/gantt.md)
- [Kanban](/componentes/kanban.md)
- [PixCode](/componentes/pix-code.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
