ChartHeatmap
Consultas por dia e hora
Quando a clínica lota
Consultas atendidas por hora, na última semana.
| 8h | 9h | 10h | 11h | 12h | 13h | 14h | 15h | 16h | 17h | 18h | 19h | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Seg | 7 | 11 | 14 | 16 | 18 | 19 | 19 | 18 | 16 | 14 | 11 | 7 |
| Ter | 6 | 9 | 11 | 14 | 15 | 16 | 16 | 15 | 14 | 11 | 9 | 6 |
| Qua | 7 | 10 | 13 | 15 | 17 | 17 | 17 | 17 | 15 | 13 | 10 | 7 |
| Qui | 5 | 8 | 10 | 12 | 14 | 14 | 14 | 14 | 12 | 10 | 8 | 5 |
| Sex | 8 | 12 | 16 | 19 | 21 | 22 | 22 | 21 | 19 | 16 | 12 | 8 |
| Sáb | 2 | 3 | 3 | 4 | 5 | 5 | Sem dado | Sem dado | Sem dado | Sem dado | Sem dado | Sem dado |
| Dom | Sem dado | Sem dado | Sem dado | Sem dado | Sem dado | Sem dado | Sem dado | Sem dado | Sem dado | Sem dado | Sem dado | Sem dado |
Zero e vazio não são a mesma coisa
| S1 | S2 | S3 | |
|---|---|---|---|
| Suporte | 4 | 0 | 9 |
| Financeiro | 12 | 7 | 3 |
| Cadastro | 1 | Sem registro | 2 |
Sem nenhuma consulta
Nenhuma consulta na semana
A grade aparece quando o primeiro paciente for atendido.
import { ChartHeatmap } from '@rivocode/ui/chart'Quando usar
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.
<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.
API
| Prop | Tipo | Padrão |
|---|---|---|
columnKeyobrigatóriaDe onde sai a coluna da grade (o eixo horizontal). | keyof Cell & string | sem padrão |
dataobrigatóriaUma linha por celula preenchida, no formato longo que a consulta devolve: `{ dia: "Seg", hora: "14h", total: 12 }`. | Cell[] | sem padrão |
labelobrigatóriaO 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. | string | sem padrão |
rowKeyobrigatóriaDe onde sai a linha da grade (o eixo vertical). | keyof Cell & string | sem padrão |
valueKeyobrigatóriaDe onde sai o numero. | keyof Cell & string | sem padrão |
classNamesClasse por parte: `grid`, `cell`, `legend`. | Partial<Record<"cell" | "grid" | "legend", string>> | sem padrão |
colorA cor do degrau mais forte. | string | "var(--rc-chart-1)" |
columnsA ordem das colunas, pela mesma regra de `rows`. | readonly string[] | sem padrão |
domainO intervalo da escala, `[menor, maior]`. | readonly [number, number] | sem padrão |
emptyO que aparece no lugar do desenho quando nao ha o que pintar: lista vazia, nenhuma celula com numero, ou todas em zero. | { title: ReactNode; description: ReactNode; action?: ReactNode; icon?: ReactNode; } | sem padrão |
formatComo o numero e escrito, na dica, na legenda e na tabela do leitor de tela. | Format | sem padrão |
labelsOs textos da peca, para trocar o idioma: `empty` e o que a leitura diz na celula sem dado, "Sem dado" sem ele. | Partial<ChartHeatmapLabels> | sem padrão |
legendA regua de cor embaixo da grade, do menor ao maior. | boolean | true |
rowsA ordem das linhas, e as que existem mesmo sem dado nenhum. | readonly string[] | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.