# Kanban

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.

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

```tsx
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.

```tsx
<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.

```tsx
{ 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.

## Importação

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

## Exemplos

### O quadro dos pedidos

```tsx
import { Badge, currencyShort } from '@rivocode/ui'
import { Kanban, type KanbanColumn, type KanbanMove } from '@rivocode/ui/dnd'
import { useState } from 'react'

type Order = { id: string; customer: string; amount: number; late?: boolean }

const BOARD: KanbanColumn<Order>[] = [
  {
    id: 'todo',
    title: 'Novo',
    items: [
      { id: '1041', customer: 'Marina Toledo', amount: 340 },
      { id: '1042', customer: 'Rafael Quintana', amount: 78, late: true },
      { id: '1043', customer: 'Helena Brandão', amount: 125 },
    ],
  },
  {
    id: 'review',
    title: 'Separando',
    limit: 2,
    items: [
      { id: '1038', customer: 'Otávio Leme', amount: 560 },
      { id: '1039', customer: 'Joana Freitas', amount: 92 },
    ],
  },
  { id: 'done', title: 'Enviado', items: [] },
]

function move(columns: KanbanColumn<Order>[], { itemId, from, to, index }: KanbanMove) {
  const card = columns.find((column) => column.id === from)?.items.find((order) => order.id === itemId)
  if (!card) return columns
  return columns.map((column) => {
    const items = column.items.filter((order) => order.id !== itemId)
    if (column.id === to) items.splice(index, 0, card)
    return { ...column, items }
  })
}

function OrderCard({ order }: { order: Order }) {
  return (
    <div className="flex flex-col gap-1.5">
      <div className="flex items-center justify-between gap-2">
        <span className="tabular-nums text-xs text-fg-muted">Pedido {order.id}</span>
        {order.late && (
          <Badge tone="danger" size="sm">
            Atrasado
          </Badge>
        )}
      </div>
      <span className="font-medium">{order.customer}</span>
      <span className="tabular-nums text-fg-muted">{currencyShort(order.amount)}</span>
    </div>
  )
}

export function Notes() {
  const [columns, setColumns] = useState(BOARD)

  return (
    <div className="w-full">
      <Kanban
        aria-label="Pedidos de hoje"
        columns={columns}
        getKey={(order) => order.id}
        getLabel={(order) => `Pedido ${order.id}`}
        onMove={(change) => setColumns((now) => move(now, change))}
        renderCard={(order) => <OrderCard order={order} />}
      />
    </div>
  )
}
```

### Acima do limite

```tsx
import { Badge, currencyShort } from '@rivocode/ui'
import { Kanban, type KanbanColumn, type KanbanMove } from '@rivocode/ui/dnd'
import { useState } from 'react'

type Order = { id: string; customer: string; amount: number; late?: boolean }

const BOARD: KanbanColumn<Order>[] = [
  {
    id: 'todo',
    title: 'Novo',
    items: [
      { id: '1041', customer: 'Marina Toledo', amount: 340 },
      { id: '1042', customer: 'Rafael Quintana', amount: 78, late: true },
      { id: '1043', customer: 'Helena Brandão', amount: 125 },
    ],
  },
  {
    id: 'review',
    title: 'Separando',
    limit: 2,
    items: [
      { id: '1038', customer: 'Otávio Leme', amount: 560 },
      { id: '1039', customer: 'Joana Freitas', amount: 92 },
    ],
  },
  { id: 'done', title: 'Enviado', items: [] },
]

function move(columns: KanbanColumn<Order>[], { itemId, from, to, index }: KanbanMove) {
  const card = columns.find((column) => column.id === from)?.items.find((order) => order.id === itemId)
  if (!card) return columns
  return columns.map((column) => {
    const items = column.items.filter((order) => order.id !== itemId)
    if (column.id === to) items.splice(index, 0, card)
    return { ...column, items }
  })
}

function OrderCard({ order }: { order: Order }) {
  return (
    <div className="flex flex-col gap-1.5">
      <div className="flex items-center justify-between gap-2">
        <span className="tabular-nums text-xs text-fg-muted">Pedido {order.id}</span>
        {order.late && (
          <Badge tone="danger" size="sm">
            Atrasado
          </Badge>
        )}
      </div>
      <span className="font-medium">{order.customer}</span>
      <span className="tabular-nums text-fg-muted">{currencyShort(order.amount)}</span>
    </div>
  )
}

export function OverLimit() {
  const [columns, setColumns] = useState<KanbanColumn<Order>[]>(() =>
    move(BOARD, { itemId: '1041', from: 'todo', to: 'review', index: 0 }),
  )

  return (
    <div className="w-full">
      <Kanban
        aria-label="Pedidos de hoje"
        columns={columns}
        getKey={(order) => order.id}
        getLabel={(order) => `Pedido ${order.id}`}
        onMove={(change) => setColumns((now) => move(now, change))}
        renderCard={(order) => <OrderCard order={order} />}
      />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `columns` | `readonly KanbanColumn<Item>[]` | sim |  | - | As colunas, com os cartoes de cada uma. |
| `getKey` | `(item: Item) => UniqueIdentifier` | sim |  | - | A identidade de cada cartao, unica no quadro inteiro, e nao so na coluna. |
| `onMove` | `(move: KanbanMove) => void` | sim |  | - | Chamado ao soltar o cartao num lugar diferente de onde ele saiu, de outra coluna ou da mesma. |
| `renderCard` | `(item: Item, state: KanbanCardState) => ReactNode` | sim |  | - | O conteudo do cartao. |
| `classNames` | `Partial<Record<"card" \| "column" \| "count" \| "empty" \| "header" \| "list" \| "title", string>>` |  |  | - |  |
| `disabled` | `boolean` |  | `false` | - | Trava o arrasto no quadro inteiro. |
| `getLabel` | `((item: Item) => string)` |  |  | - | O nome do cartao nos anuncios: "Pedido 1043". |
| `labels` | `Partial<KanbanLabels>` |  |  | - | Os textos da contagem, da coluna vazia, do limite e dos anuncios, para outra lingua. |
| `moveMenu` | `boolean` |  | `true` | - | O botao "Mover" no canto de cada cartao, que abre um menu com as outras colunas e com subir e descer na mesma. |
| `onOpen` | `((item: Item) => void)` |  |  | - | Abre o cartao: Enter no cartao focado ou o clique sem arrasto. |

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)
- [PixCode](/componentes/pix-code.md)
- [QRCode](/componentes/qr-code.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
