# ChartHeatmap

Uma grade de linhas por colunas em que a cor de cada célula diz o tamanho do
número: consultas por dia da semana e hora, chamados por equipe e semana.

```tsx
<ChartHeatmap
  data={consultas}
  rowKey="dia"
  columnKey="hora"
  valueKey="total"
  rows={['Seg', 'Ter', 'Qua', 'Qui', 'Sex', 'Sáb', 'Dom']}
  label="Consultas atendidas por dia da semana e hora"
/>
```

O `data` vem no formato longo, uma linha por célula, que é o que um
`GROUP BY dia, hora` devolve. `rows` e `columns` dão a ordem e trazem para a
grade a linha que não teve nenhum registro: sem eles, o domingo sem consulta
some da tabela em vez de aparecer vazio.

## A escala

São cinco degraus de uma cor só, do mais ralo ao mais cheio. O degrau mais forte
é a própria cor da série (`var(--rc-chart-1)`, ou a do `color`) e os quatro de
baixo são ela mesma em tinta mais rala sobre o fundo, então a escala acompanha o
tema sem nenhuma cor nova. A régua embaixo mostra os cinco degraus entre o menor
e o maior número.

O intervalo sai dos dados: de zero (ou do menor valor, se houver negativo) até o
maior. Duas grades lado a lado que precisam ser comparadas pedem a **mesma
régua**, e é para isso que existe o `domain`: sem ele, o degrau mais cheio de
cada uma quer dizer um número diferente.

Os rótulos de coluna aparecem de tanto em tanto quando não cabem todos: a
peça mede a largura das células, sem a coluna dos rótulos de linha, e deixa uns
quarenta pixels para cada rótulo que escreve, então 24 horas num cartão de
celular saem de quatro em quatro, sem reticências. O rótulo que não aparece
continua na tabela do leitor de tela.

O rótulo de linha ocupa o que precisa até 40% da grade, e nunca mais de
`10rem`: o nome comprido de um cliente termina em reticências, e o resto da
largura fica com as células. O nome inteiro está na dica e na tabela.

Uma grade sem variação (tudo zero, ou um `domain` com os dois números iguais)
pinta o degrau mais ralo, e não o mais cheio: sem diferença para mostrar, a
grade não grita.

## Zero não é vazio

A célula com `0` é um valor, e pinta o primeiro degrau. A célula sem dado
(a combinação que não veio no `data`, ou veio com `null`) não tem tinta
nenhuma e leva uma borda tracejada. Os dois se leem diferentes de propósito:
"ninguém foi atendido às 22h" e "não registramos as 22h" são respostas diferentes à mesma
pergunta, e uma grade que pinta os dois do mesmo jeito mente numa delas. A dica,
a tabela escondida e a régua dizem "Sem dado", ou o que você escrever em
`labels.empty`.

## Dica, teclado e leitor de tela

O ponteiro sobre uma célula abre a dica com a linha, a coluna e o número. A
grade inteira é **uma parada só** no Tab, e dali as setas andam célula a
célula (`Home` e `End` vão às pontas da linha, e com `Ctrl` às pontas da
grade), com a mesma dica aberta e o mesmo texto anunciado. Cento e sessenta e oito
paradas de Tab dentro de um cartão seriam um obstáculo, e é a mesma decisão do
`Tracker`.

Para o leitor de tela o desenho não é a fonte: ao lado dele há uma **tabela de
verdade**, escondida da vista, com a legenda que você escreveu em `label`, a
linha e a coluna como cabeçalhos e o número escrito em cada célula. É ela que se
navega com os comandos de tabela, e é por isso que `label` é obrigatório.

## O número não entra na célula

Numa grade de sete por vinte e quatro a célula tem vinte e poucos pixels, e o
número escrito ali não cabe nem se lê. Ele mora na dica e na tabela. Quando a
pergunta é o número exato de cada cruzamento, e não o padrão, a peça certa é o
`DataTable`.

## Movimento

A grade entra esmaecendo, e quando os dados mudam cada célula troca de degrau
em `--rc-duration-slow`. Com "reduzir movimento", a troca é seca.

## Sem dado

`empty` é o mesmo objeto do `ChartContainer` e do `DataTable`: `title`,
`description` obrigatória, `action` e `icon` opcionais. Ele aparece no lugar do
desenho quando não há o que pintar: a lista vazia, nenhuma célula com número,
ou todas em zero. Sem ele, a grade desenha só as linhas e colunas que `rows` e `columns` declararem, todas tracejadas.

A peça não tem os quatro finais de uma consulta: carregando, erro e vazio vêm do
`QueryBoundary` em volta dela.

## Quando não usar

Para um estado por período numa linha só (a disponibilidade do mês, as últimas
90 entregas), use `Tracker`: ele cabe no rodapé de um `Stat` e responde "piorou
ontem?" sem a segunda dimensão que a grade pede.

Quando a pergunta é o número exato de cada célula, a grade não serve: a cor diz
o degrau, e não o valor. Aí é `DataTable` ou `Table`. E a proporção entre
categorias, sem linha por coluna, é `ChartDonut` ou `ChartTreemap`.

## No React Native

Traduz, em `@rivocode/ui-native/chart`, com as mesmas props: `rowKey`, `columnKey`, `valueKey`, `rows`, `columns`, `domain`, `labels`, `legend`, `format`. A escala é a mesma, cinco degraus de uma cor só, e os alfas vêm da mesma constante do web, gerada em `native/src/shared/`. Zero pinta o primeiro degrau e a célula sem dado tem borda tracejada, igual.

Uma mudança de tipo: `color` é papel de token (`chart-3`).

**O que muda é como se lê uma célula.** No web o ponteiro pousa e a dica abre, e o leitor de tela navega uma tabela escondida. No celular não há dica nem tabela: o dedo toca ou arrasta sobre a grade e escolhe a célula debaixo dele, que ganha contorno, e a linha, a coluna e o número aparecem escritos embaixo da grade. Para o leitor de tela a grade é **uma parada `adjustable` só**, que anda célula a célula com o gesto de subir e descer, a mesma decisão do `Tracker`: cento e sessenta e oito paradas dentro de um cartão seriam um obstáculo, e o valor de cada uma vai inteiro no `accessibilityValue`.

Os rótulos de coluna aparecem no máximo seis, e não pela largura medida como no web: a tela do celular é estreita sempre, e o rótulo que não aparece continua sendo dito na leitura.

As partes vestem pelo mesmo `classNames` do web: `grid`, a parada que recebe o arrasto, `cell` e `legend`. Com `empty` (o formato do `ChartContainer`), a grade sem número ou toda em zero dá lugar ao estado vazio; sem ele, a grade em zero continua pintando o degrau mais ralo.

## Importação

```tsx
import { ChartHeatmap } from '@rivocode/ui/chart'
```

## Exemplos

### Consultas por dia e hora

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@rivocode/ui'
import { ChartHeatmap } from '@rivocode/ui/chart'

const DAYS = ['Seg', 'Ter', 'Qua', 'Qui', 'Sex', 'Sáb', 'Dom']

const HOURS = Array.from({ length: 12 }, (_, index) => `${index + 8}h`)

const BUSY: Record<string, number> = {
  Seg: 1.2,
  Ter: 1,
  Qua: 1.1,
  Qui: 0.9,
  Sex: 1.4,
  Sáb: 0.3,
  Dom: 0,
}

const VISITS = DAYS.flatMap((day) =>
  HOURS.map((hour, index) => ({
    day,
    hour,
    total:
      day === 'Dom' ? null : Math.round(BUSY[day]! * (6 + 10 * Math.sin((index / 11) * Math.PI))),
  })),
).filter((cell) => !(cell.day === 'Sáb' && Number.parseInt(cell.hour) > 13))

const TICKETS = [
  { team: 'Suporte', week: 'S1', open: 4 },
  { team: 'Suporte', week: 'S2', open: 0 },
  { team: 'Suporte', week: 'S3', open: 9 },
  { team: 'Financeiro', week: 'S1', open: 12 },
  { team: 'Financeiro', week: 'S2', open: 7 },
  { team: 'Financeiro', week: 'S3', open: 3 },
  { team: 'Cadastro', week: 'S1', open: 1 },
  { team: 'Cadastro', week: 'S3', open: 2 },
]

export function EmissionsByHour() {
  return (
    <Card className="w-full max-w-[36rem]">
      <CardHeader>
        <CardTitle>Quando a clínica lota</CardTitle>
        <CardDescription>Consultas atendidas por hora, na última semana.</CardDescription>
      </CardHeader>
      <CardContent>
        <ChartHeatmap
          data={VISITS}
          rowKey="day"
          columnKey="hour"
          valueKey="total"
          rows={DAYS}
          columns={HOURS}
          label="Consultas atendidas por dia da semana e hora"
        />
      </CardContent>
    </Card>
  )
}

const TICKETS = [
  { team: 'Suporte', week: 'S1', open: 4 },
  { team: 'Suporte', week: 'S2', open: 0 },
  { team: 'Suporte', week: 'S3', open: 9 },
  { team: 'Financeiro', week: 'S1', open: 12 },
  { team: 'Financeiro', week: 'S2', open: 7 },
  { team: 'Financeiro', week: 'S3', open: 3 },
  { team: 'Cadastro', week: 'S1', open: 1 },
  { team: 'Cadastro', week: 'S3', open: 2 },
]
```

### Zero e vazio não são a mesma coisa

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@rivocode/ui'
import { ChartHeatmap } from '@rivocode/ui/chart'

const TICKETS = [
  { team: 'Suporte', week: 'S1', open: 4 },
  { team: 'Suporte', week: 'S2', open: 0 },
  { team: 'Suporte', week: 'S3', open: 9 },
  { team: 'Financeiro', week: 'S1', open: 12 },
  { team: 'Financeiro', week: 'S2', open: 7 },
  { team: 'Financeiro', week: 'S3', open: 3 },
  { team: 'Cadastro', week: 'S1', open: 1 },
  { team: 'Cadastro', week: 'S3', open: 2 },
]

export function ZeroIsNotEmpty() {
  return (
    <div className="w-full max-w-80">
      <ChartHeatmap
        data={TICKETS}
        rowKey="team"
        columnKey="week"
        valueKey="open"
        color="var(--rc-chart-3)"
        label="Chamados abertos por equipe e semana"
        labels={{ empty: "Sem registro" }}
      />
    </div>
  )
}
```

### Sem nenhuma consulta

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@rivocode/ui'
import { ChartHeatmap } from '@rivocode/ui/chart'

export function EmptyHeatmap() {
  return (
    <div className="w-full max-w-lg">
      <ChartHeatmap
        data={[] as { day: string; hour: string; total: number }[]}
        rowKey="day"
        columnKey="hour"
        valueKey="total"
        label="Consultas por dia e hora"
        empty={{
          title: 'Nenhuma consulta na semana',
          description: 'A grade aparece quando o primeiro paciente for atendido.',
        }}
      />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `columnKey` | `keyof Cell & string` | sim |  | - | De onde sai a coluna da grade (o eixo horizontal). |
| `data` | `Cell[]` | sim |  | - | Uma linha por celula preenchida, no formato longo que a consulta devolve: `{ dia: "Seg", hora: "14h", total: 12 }`. |
| `label` | `string` | sim |  | - | O que a grade mede, por extenso: vira o nome do grupo e a legenda da tabela que o leitor de tela le no lugar do desenho. |
| `rowKey` | `keyof Cell & string` | sim |  | - | De onde sai a linha da grade (o eixo vertical). |
| `valueKey` | `keyof Cell & string` | sim |  | - | De onde sai o numero. |
| `classNames` | `Partial<Record<"cell" \| "grid" \| "legend", string>>` |  |  | - | Classe por parte: `grid`, `cell`, `legend`. |
| `color` | `string` |  | `"var(--rc-chart-1)"` | - | A cor do degrau mais forte. |
| `columns` | `readonly string[]` |  |  | - | A ordem das colunas, pela mesma regra de `rows`. |
| `domain` | `readonly [number, number]` |  |  | - | O intervalo da escala, `[menor, maior]`. |
| `empty` | `{ title: ReactNode; description: ReactNode; action?: ReactNode; icon?: ReactNode; }` |  |  | - | O que aparece no lugar do desenho quando nao ha o que pintar: lista vazia, nenhuma celula com numero, ou todas em zero. |
| `format` | `Format` |  |  | - | Como o numero e escrito, na dica, na legenda e na tabela do leitor de tela. |
| `labels` | `Partial<ChartHeatmapLabels>` |  |  | - | Os textos da peca, para trocar o idioma: `empty` e o que a leitura diz na celula sem dado, "Sem dado" sem ele. |
| `legend` | `boolean` |  | `true` | - | A regua de cor embaixo da grade, do menor ao maior. |
| `rows` | `readonly string[]` |  |  | - | A ordem das linhas, e as que existem mesmo sem dado nenhum. |

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

## Ver também

- [ChartContainer](/componentes/chart-container.md)
- [ChartDonut](/componentes/chart-donut.md)
- [ChartFunnel](/componentes/chart-funnel.md)
- [ChartGauge](/componentes/chart-gauge.md)
- [ChartRadial](/componentes/chart-radial.md)
- [ChartTreemap](/componentes/chart-treemap.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
