ChartTreemap
Vendas por categoria
Vendas por categoria
Categorias da loja, no mês. A área é proporcional ao valor.
- Eletrônicos: R$ 182,4K (43%)
- Casa e cozinha: R$ 96,3K (22,7%)
- Moda: R$ 71,9K (16,9%)
- Esporte: R$ 38,2K (9%)
- Beleza: R$ 22,7K (5,3%)
- Livros: R$ 9,8K (2,3%)
- Papelaria: R$ 3,1K (0,7%)
O rótulo que não cabe some
- Fotos: 38,2 GB (57,1%)
- Vídeos: 21,4 GB (32%)
- Documentos: 6,9 GB (10,3%)
- Planilhas: 0,4 GB (0,6%)
Soma zero, com o vazio
Nenhuma venda no mês
O mapa aparece quando a loja vender o primeiro produto.
import { ChartTreemap } from '@rivocode/ui/chart'Quando usar
Um retângulo repartido em áreas proporcionais ao valor de cada categoria: as vendas do mês por categoria de produto, o armazenamento por tipo de arquivo.
<ChartTreemap
data={porCategoria}
valueKey="total"
nameKey="categoria"
config={categorias}
format="currencyShort"
label="Vendas do mês por categoria de produto"
className="h-72"
/>
A área sai de um algoritmo de retângulos quase quadrados (o squarified de
Bruls, Huizing e van Wijk), que é o que deixa comparar tamanho a olho. O
config é o mesmo da rosca: nome legível e cor por categoria, e sem cor cada
uma pega a próxima da paleta, na ordem de data. A altura é sua, por classe:
sem ela, h-64.
O rótulo some quando não cabe
Cada retângulo escreve o nome e o valor quando cabem os dois, só o nome quando não sobra altura para o valor, e nada quando nem o nome cabe inteiro. O nome comprido quebra entre palavras e ocupa quantas linhas a altura deixar: "Ver os horários livres da equipe" numa caixa estreita e alta sai em duas linhas, e só some a caixa em que nem as linhas cabem na altura, ou em que uma palavra sozinha não cabe na largura. Não há reticências: "Eletrôn…" num retângulo de quarenta pixels não diz qual categoria é, e ocupa o lugar que faria o retângulo se ler como pequeno, que é a informação certa. A conta usa a medida real da caixa, e antes de a caixa ser medida nenhum rótulo é desenhado, em vez de adivinhar.
O que some do desenho continua em três lugares: na dica, que o ponteiro abre sobre qualquer retângulo; no teclado, porque o mapa é uma parada só no Tab e as setas percorrem as categorias de cima para baixo; e numa lista escondida da vista, com nome, valor e fatia de cada uma, que é o que o leitor de tela lê. Categoria com zero, que não ganha área nenhuma, também está nela.
As cores e o contraste
O retângulo é a cor da categoria a 30% sobre o fundo, com um contorno na cor
cheia, e o rótulo é escrito em fg por cima. Não é a cor cheia com texto claro,
e a razão é medida: a lima escura do tema claro com texto branco dá 4,10:1,
abaixo dos 4,5 de texto. Na tinta a 30%, o pior par das oito cores de série
nos dois temas é 6,77:1, e a guarda de contraste mede os dezesseis a cada
commit. Cor escrita à mão no config não entra nessa medida.
Movimento
O mapa entra esmaecendo, e quando os dados mudam cada retângulo anda até a
posição e o tamanho novos 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 a lista vem vazia ou a soma dá zero. Sem ele, o mapa fica com a moldura vazia, e a lista do leitor de tela continua dizendo cada categoria.
Direita para a esquerda
No rtl as caixas se espelham: a maior categoria abre à direita, e a seta que
anda para a frente (a da esquerda) vai para a caixa que está à esquerda na tela.
Quando não usar
Até seis categorias, use ChartDonut: com poucas fatias a rosca lê melhor e põe
o total no meio. O mapa ganha quando são muitas, e paga com o rótulo que some no
retângulo pequeno.
Quando o valor exato de cada categoria importa mais que a proporção, use
DataTable ou Table: o mapa compara tamanho a olho e cala o número dos
retângulos menores. E o padrão numa grade de linha por coluna é ChartHeatmap.
Quando a hierarquia é para navegar, abrir uma pasta e ver o que tem dentro,
é o Tree: o treemap mostra um nível só, e não é clicável.
No React Native
Traduz, em @rivocode/ui-native/chart, com as mesmas props: valueKey, nameKey, config, format. A geometria é a mesma função do web (o squarified, gerado em native/src/shared/), e a regra do rótulo também: nome e valor quando cabem os dois, só o nome quando não sobra altura para o valor, o nome comprido quebrado em quantas linhas a altura deixar, nada quando nem o nome cabe, e nada antes do onLayout medir a caixa. A tinta a 30% com fg por cima é a mesma, e os dezesseis pares estão no mapa de contraste do nativo.
Uma mudança de tipo: o config.color é papel de token, como em toda a família.
O que muda é como se lê uma categoria. Aqui são poucas (acima de uma dúzia o treemap para de informar), e poucas categorias viram poucas paradas: cada retângulo é um botão com nome, valor e fatia, a decisão da legenda da rosca e não a do Tracker. Tocar acende o contorno e escreve a leitura embaixo, no lugar da dica do web; tocar de novo apaga. Por isso não há label: o web o usa para nomear o grupo e a lista escondida, e no celular nem um nem outro existe. O título do cartão faz esse papel.
As partes vestem pelo mesmo classNames do web: cell, o bloco de cada categoria, e label, o nome e o valor dentro dele. Com empty (o formato do ChartContainer), lista vazia ou soma zero mostram o estado vazio no lugar dos blocos.
API
| Prop | Tipo |
|---|---|
dataobrigatóriaAs categorias. | Item[] |
labelobrigatóriaO que o mapa mede, por extenso: vira o nome do grupo e da lista escondida. | string |
nameKeyobrigatóriaDe onde sai o nome de cada categoria. | keyof Item & string |
valueKeyobrigatóriaDe onde sai o numero, que vira area. | keyof Item & string |
classNamesClasse por parte: `cell`, `label`. | Partial<Record<"cell" | "label", string>> |
configNome legivel e cor por categoria, o mesmo formato da rosca. | ChartConfig |
emptyO que aparece no lugar do desenho quando a lista vem vazia ou a soma e zero. | { title: ReactNode; description: ReactNode; action?: ReactNode; icon?: ReactNode; } |
formatComo o numero e escrito, no rotulo, na dica e na lista do leitor de tela. | Format |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.