Pular para o conteúdo
Dados

Kanban

/componentes/kanban.mdmarkdown cru, para quem lê com agent em vez de olho

O quadro dos pedidos

Novo

3 cartões
  • Pedido 1041
    Marina ToledoR$ 340
  • Pedido 1042Atrasado
    Rafael QuintanaR$ 78
  • Pedido 1043
    Helena BrandãoR$ 125

Separando

2 de 2 cartões
  • Pedido 1038
    Otávio LemeR$ 560
  • Pedido 1039
    Joana FreitasR$ 92

Enviado

0 cartões

    Nenhum cartão. Solte um aqui.

    Acima do limite

    Novo

    2 cartões
    • Pedido 1042Atrasado
      Rafael QuintanaR$ 78
    • Pedido 1043
      Helena BrandãoR$ 125

    Separando

    3 de 2 cartõesAcima do limite
    • Pedido 1041
      Marina ToledoR$ 340
    • Pedido 1038
      Otávio LemeR$ 560
    • Pedido 1039
      Joana FreitasR$ 92

    Enviado

    0 cartões

      Nenhum cartão. Solte um aqui.

      Importar
      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 de Badge mostra mais linhas, ordena e filtra. O quadro é para quem move cartão o dia inteiro.
      • Etapas de um único processo são Steps. O Steps diz em que passo uma coisa está; o Kanban mostra 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

      PropTipoPadrão
      columnsobrigatória

      As colunas, com os cartoes de cada uma.

      readonly KanbanColumn<Item>[]sem padrão
      getKeyobrigatória

      A identidade de cada cartao, unica no quadro inteiro, e nao so na coluna.

      (item: Item) => UniqueIdentifiersem padrão
      onMoveobrigatória

      Chamado ao soltar o cartao num lugar diferente de onde ele saiu, de outra coluna ou da mesma.

      (move: KanbanMove) => voidsem padrão
      renderCardobrigatória

      O conteudo do cartao.

      (item: Item, state: KanbanCardState) => ReactNodesem padrão
      classNamesPartial<Record<"card" | "column" | "count" | "empty" | "header" | "list" | "title", string>>sem padrão
      disabled

      Trava o arrasto no quadro inteiro.

      booleanfalse
      getLabel

      O nome do cartao nos anuncios: "Pedido 1043".

      ((item: Item) => string)sem padrão
      labels

      Os textos da contagem, da coluna vazia, do limite e dos anuncios, para outra lingua.

      Partial<KanbanLabels>sem padrão
      moveMenu

      O botao "Mover" no canto de cada cartao, que abre um menu com as outras colunas e com subir e descer na mesma.

      booleantrue
      onOpen

      Abre 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.

      @rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

      Feito por RivoCode.