Kanban
O quadro dos pedidos
Novo
3 cartões- Pedido 1041Marina ToledoR$ 340
- Pedido 1042AtrasadoRafael QuintanaR$ 78
- Pedido 1043Helena BrandãoR$ 125
Separando
2 de 2 cartões- Pedido 1038Otávio LemeR$ 560
- Pedido 1039Joana FreitasR$ 92
Enviado
0 cartõesNenhum cartão. Solte um aqui.
Acima do limite
Novo
2 cartões- Pedido 1042AtrasadoRafael QuintanaR$ 78
- Pedido 1043Helena BrandãoR$ 125
Separando
3 de 2 cartõesAcima do limite- Pedido 1041Marina ToledoR$ 340
- Pedido 1038Otávio LemeR$ 560
- Pedido 1039Joana FreitasR$ 92
Enviado
0 cartõesNenhum cartão. Solte um aqui.
import { Kanban } from '@rivocode/ui/dnd'Quando usar
O quadro de colunas: cada coluna é uma situação, cada cartão é uma coisa que
anda entre elas. Tarefas que vão de "A fazer" a "Feito", pedidos que vão de
"Recebido" a "Entregue". Os cartões arrastam entre colunas e dentro delas, com o
ponteiro, com o dedo e com o teclado. Vive em @rivocode/ui/dnd, atrás do
@dnd-kit/core e do @dnd-kit/sortable, que são dependências opcionais.
npm install @dnd-kit/core @dnd-kit/sortable
import { Kanban } from '@rivocode/ui/dnd'
const [columns, setColumns] = useState([
{ id: 'todo', title: 'Novo', items: received },
{ id: 'review', title: 'Separando', items: picking, limit: 4 },
{ id: 'done', title: 'Enviado', items: shipped },
])
<Kanban
aria-label="Pedidos de hoje"
columns={columns}
getKey={(order) => order.id}
getLabel={(order) => `Pedido ${order.number}`}
onMove={({ itemId, from, to, index }) => setColumns((now) => move(now, itemId, from, to, index))}
renderCard={(order) => (
<div className="flex flex-col gap-1">
<span className="font-medium">{order.customer}</span>
<span className="text-fg-muted">{currencyShort(order.amount)}</span>
</div>
)}
/>
A peça é controlada
O quadro não guarda cartão nenhum. Durante o arrasto ele mostra onde o cartão
vai cair (é o único estado que ele tem), e ao soltar pede a mudança por
onMove({ itemId, from, to, index }): a chave do cartão, a coluna de onde ele
saiu, a coluna onde parou e a posição final dentro dela, contando do zero. Quem
muda columns é você, e o quadro desenha o que voltar. Sem mudar, o cartão
volta para onde estava.
É isso que deixa a mudança de situação passar pelo servidor antes: mudar o pedido de "Separando" para "Enviado" costuma ser uma chamada, e ela pode recusar.
Soltar no mesmo lugar, soltar fora de qualquer coluna e cancelar com Esc não
chamam onMove.
getKey é a identidade do cartão, única no quadro inteiro, e não só na coluna.
Contagem e limite
Cada coluna diz quantos cartões tem, ao lado do nome. limit liga o limite de
trabalho em andamento: a contagem vira "3/4", e acima do limite ela fica no
tom de atenção e diz "Acima do limite" em texto, com ícone. Cor nunca é o único
sinal.
O limite avisa e não tranca: o cartão continua entrando, porque às vezes a coluna precisa passar do limite por um dia, e quem decide isso é a pessoa. O anúncio para o leitor de tela diz quando o cartão fez a coluna passar: "A coluna Separando passa do limite de 4.".
Coluna vazia
Coluna sem cartão mostra uma área tracejada, "Nenhum cartão. Solte um aqui.", e ela inteira aceita o cartão. Enquanto um cartão passa por cima, a coluna que vai recebê-lo ganha o anel de foco.
Teclado e leitor de tela
O cartão inteiro é a alça, e recebe foco com Tab.
| Tecla | O que faz |
|---|---|
| Espaço ou Enter | pega o cartão (com onOpen, só o Espaço) |
| Setas para cima e para baixo | movem dentro da coluna |
| Setas para os lados | levam o cartão para a coluna vizinha |
| Espaço ou Enter | solta |
| Esc | cancela, e o cartão volta para onde estava |
Cada passo é anunciado com o nome que getLabel devolve e o nome da coluna:
"Cartão Pedido 1043 movido para Separando, posição 2 de 3.". labels troca
esses textos, a contagem, o aviso de limite e o texto da coluna vazia.
Abrir o cartão
onOpen recebe o item quando a pessoa abre o cartão: Enter no cartão focado,
ou o clique que não virou arrasto. Com ele, o Espaço continua pegando e o
Enter passa a abrir, e as instruções que o leitor de tela ouve ganham a
frase de labels.open ("Enter abre o cartão."). Durante o arrasto o Enter
continua soltando, como sempre.
<Kanban
columns={columns}
getKey={(order) => order.id}
getLabel={(order) => `Pedido ${order.number}`}
onMove={mover}
onOpen={(order) => setAberto(order.id)}
renderCard={(order) => <span>{order.customer}</span>}
/>
O detalhe que abre é um Sheet ou a página do pedido; o cartão não ganha
botão de abrir dentro dele.
Título da coluna com mais que texto
title aceita um nó: o ponto de cor da situação, um ícone, a contagem do
servidor. O que os anúncios, o menu de mover e a dica do título falam é texto,
e vem de label. Sem label, o título em texto serve; título que é nó e não
tem label sai com o id da coluna nos anúncios, então passe os dois.
{ id: 'late', title: <span className="flex items-center gap-1.5"><TriangleAlert aria-hidden="true" className="size-3.5 text-danger-text" />Atrasado</span>, label: 'Atrasado', items: late }
Mover sem arrastar
O teclado resolve quem não usa o mouse, mas não quem usa o ponteiro sem conseguir segurá-lo: o toque de um dedo só, o mouse de quem treme, o controle por voz. A WCAG 2.5.7 pede para eles um caminho de ponteiro único, e o teclado não conta.
Por isso cada cartão traz um botão "Mover" no canto, que abre um Menu com
"Para cima" e "Para baixo" (só os que cabem) e, sob "Mover para", as outras
colunas. Escolher uma coluna leva o cartão ao fim dela; os três chamam o mesmo
onMove({ itemId, from, to, index }) do arrasto, o movimento é anunciado com o
mesmo texto, e o foco volta ao botão do cartão no lugar novo. É o desenho que o
Trello e o Jira usam.
O botão nasce ligado. moveMenu={false} o tira, para o quadro em que outra
ação da tela já move o cartão, e disabled o tira junto com o arrasto.
labels.moveCard dá o nome do botão ("Mover Pedido 1043"), labels.moveTo o
título do grupo das colunas, e labels.up e labels.down os dois itens da
mesma coluna.
No celular
A fileira de colunas rola de lado e encaixa uma coluna por vez. Deslizar o dedo sobre um cartão rola o quadro; para arrastar, a pessoa segura o cartão um instante antes de mover. Sem isso, todo gesto de rolar pegaria o primeiro cartão embaixo do dedo.
Movimento
Os cartões da coluna abrem espaço com a mola espacial dos tokens, e o cartão que
anda segue o ponteiro numa cópia com shadow-3, enquanto o lugar de origem fica
tracejado. Ao soltar, a cópia assenta no lugar com a mesma mola
(--rc-duration-spatial e --rc-ease-spatial), e pelo teclado ela anda de
posição em posição com a mola também. Com "reduzir movimento", os tokens vão a
zero: a cópia pula de lugar e some sem assentar.
Conteúdo do cartão
renderCard desenha o miolo; a moldura, o foco e a alça são da peça. Como o
cartão inteiro é um botão de arrastar, não ponha outro botão dentro do que o
renderCard devolve: controle dentro de controle confunde o leitor de tela e
rouba o clique. Para abrir o detalhe, use o onOpen.
A regra é sobre o miolo, e não proíbe ação no cartão. O botão "Mover" da peça não fica dentro da alça: ele é irmão dela, no mesmo item da lista, posto por cima do canto. O cartão continua sendo um controle só, e o botão é a segunda parada do Tab, com nome próprio. A moldura reserva o canto para ele, e o miolo não precisa saber que ele existe.
Partes
classNames alcança column, header, title, count, list, card e
empty. O card veste também a cópia que segue o ponteiro, para as duas
saírem iguais.
Quando não usar
- Um item que só muda de posição é
SortableList. Se não há colunas (só uma fila que a pessoa ordena), o quadro é moldura sobrando. - Situação que só se lê é
DataTable. Quando a pessoa consulta muitos pedidos e raramente muda a situação de uma, a tabela com uma coluna deBadgemostra mais linhas, ordena e filtra. O quadro é para quem move cartão o dia inteiro. - Etapas de um único processo são
Steps. OStepsdiz em que passo uma coisa está; oKanbanmostra muitas coisas, cada uma no seu passo.
No React Native
Não porta, e não é fila: é decisão. O quadro existe para o olho ver as colunas lado a lado, e a 390px cabe uma. Arrastar um cartão para a coluna ao lado quer dizer segurar o dedo enquanto a fileira rola por baixo dele até uma coluna que ainda não está na tela, e o dedo que arrasta é o mesmo que precisaria rolar. No navegador do celular o Kanban do web continua de pé, com a fileira rolando uma coluna por vez e o cartão saindo do lugar só depois de o dedo segurá-lo, mas é o recurso de quem abriu uma tela de mesa no telefone, e não o desenho de um aplicativo.
No telefone, cada coluna é uma lista, e mudar de coluna é uma ação. As colunas viram Tabs (ou seções de uma DataList), a ordem dentro da coluna é a SortableList de @rivocode/ui-native/dnd, e cada cartão ganha um Menu com "Mover para" e o nome das outras colunas. É o mesmo onMove({ itemId, from, to, index }) do web do lado de quem guarda o estado, e é o caminho que o leitor de tela já faria de qualquer jeito. O Kanban do web passou a trazer esse mesmo menu no botão "Mover" de cada cartão, com "Para cima", "Para baixo" e as outras colunas: a tela do celular monta o mesmo desenho com o Menu daqui.
API
| Prop | Tipo | Padrão |
|---|---|---|
columnsobrigatóriaAs colunas, com os cartoes de cada uma. | readonly KanbanColumn<Item>[] | sem padrão |
getKeyobrigatóriaA identidade de cada cartao, unica no quadro inteiro, e nao so na coluna. | (item: Item) => UniqueIdentifier | sem padrão |
onMoveobrigatóriaChamado ao soltar o cartao num lugar diferente de onde ele saiu, de outra coluna ou da mesma. | (move: KanbanMove) => void | sem padrão |
renderCardobrigatóriaO conteudo do cartao. | (item: Item, state: KanbanCardState) => ReactNode | sem padrão |
classNames | Partial<Record<"card" | "column" | "count" | "empty" | "header" | "list" | "title", string>> | sem padrão |
disabledTrava o arrasto no quadro inteiro. | boolean | false |
getLabelO nome do cartao nos anuncios: "Pedido 1043". | ((item: Item) => string) | sem padrão |
labelsOs textos da contagem, da coluna vazia, do limite e dos anuncios, para outra lingua. | Partial<KanbanLabels> | sem padrão |
moveMenuO botao "Mover" no canto de cada cartao, que abre um menu com as outras colunas e com subir e descer na mesma. | boolean | true |
onOpenAbre o cartao: Enter no cartao focado ou o clique sem arrasto. | ((item: Item) => void) | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.