SortableList
A fila de prioridades
Corrigir o login pelo celular
Tarefa 211 · Bruna · prazo 26/09
3 hPróximaAtualizar a página de preços
Tarefa 212 · Caio · prazo 27/09
1 hResponder o chamado da Vila Verde
Tarefa 213 · Denise · prazo 30/09
30 minMigrar o banco de testes
Tarefa 214 · Otávio · prazo 02/10
1 diaPreparar a demonstração de outubro
Tarefa 215 · Bruna · prazo 05/10
4 h
Horizontal, com a linha inteira como alça
- 1Separar o pedido
- 2Embalar
- 3Gerar a etiqueta de frete
- 4Entregar à transportadora
Desabilitada enquanto salva
Corrigir o login pelo celular
Atualizar a página de preços
Responder o chamado da Vila Verde
import { SortableList } from '@rivocode/ui/dnd'Quando usar
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.
npm install @dnd-kit/core @dnd-kit/sortable
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:
<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.
<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
EmptyStateno 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 colunasortableresolve com um clique e sem ninguém mexer em nada. ASortableListé 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}.
API
| Prop | Tipo | Padrão |
|---|---|---|
getKeyobrigatóriaA identidade de cada item. | (item: Item) => UniqueIdentifier | sem padrão |
itemsobrigatóriaOs itens, na ordem de agora. | readonly Item[] | sem padrão |
onReorderobrigatóriaA ordem nova, ja montada, ao soltar num lugar diferente de onde o item saiu. | (items: Item[], move: SortableListMove) => void | sem padrão |
renderItemobrigatóriaO desenho de cada item. | (item: Item, state: SortableItemState) => ReactNode | sem padrão |
classNames | Partial<Record<"content" | "handle" | "item", string>> | sem padrão |
disabledTrava o arrasto inteiro, e a alca sai desabilitada. | boolean | false |
getLabelO nome do item nos anuncios e no nome da alca: "Pedido 1043" vira "Item Pedido 1043 movido para a posicao 3 de 8". | ((item: Item) => string) | sem padrão |
handleDesenha a alca, um `IconButton` com o icone de pegar, no inicio de cada item, e so ela arrasta. | boolean | true |
labelsOs 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"). | Partial<SortableListLabels> | sem padrão |
moveMenuO botao "Mover" no fim de cada item, que abre um menu com o inicio, um passo para cada lado e o fim. | boolean | true |
orientationO eixo da lista. | "horizontal" | "vertical" | "vertical" |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.