# ChartTreemap

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.

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

## Importação

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

## Exemplos

### Vendas por categoria

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

const BY_CATEGORY = [
  { code: 'eletronicos', total: 182_400 },
  { code: 'casa', total: 96_300 },
  { code: 'moda', total: 71_900 },
  { code: 'esporte', total: 38_200 },
  { code: 'beleza', total: 22_700 },
  { code: 'livros', total: 9_800 },
  { code: 'papelaria', total: 3_100 },
]

const CATEGORIES: ChartConfig = {
  eletronicos: { label: 'Eletrônicos' },
  casa: { label: 'Casa e cozinha' },
  moda: { label: 'Moda' },
  esporte: { label: 'Esporte' },
  beleza: { label: 'Beleza' },
  livros: { label: 'Livros' },
  papelaria: { label: 'Papelaria' },
}

const STORAGE = [
  { kind: 'Fotos', total: 38.2 },
  { kind: 'Vídeos', total: 21.4 },
  { kind: 'Documentos', total: 6.9 },
  { kind: 'Planilhas', total: 0.4 },
]

export function RevenueByService() {
  return (
    <Card className="w-full max-w-[34rem]">
      <CardHeader>
        <CardTitle>Vendas por categoria</CardTitle>
        <CardDescription>
          Categorias da loja, no mês. A área é proporcional ao valor.
        </CardDescription>
      </CardHeader>
      <CardContent>
        <ChartTreemap
          data={BY_CATEGORY}
          valueKey="total"
          nameKey="code"
          config={CATEGORIES}
          format="currencyShort"
          label="Vendas do mês por categoria de produto"
          className="h-72"
        />
      </CardContent>
    </Card>
  )
}

const STORAGE = [
  { kind: 'Fotos', total: 38.2 },
  { kind: 'Vídeos', total: 21.4 },
  { kind: 'Documentos', total: 6.9 },
  { kind: 'Planilhas', total: 0.4 },
]
```

### O rótulo que não cabe some

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

const STORAGE = [
  { kind: 'Fotos', total: 38.2 },
  { kind: 'Vídeos', total: 21.4 },
  { kind: 'Documentos', total: 6.9 },
  { kind: 'Planilhas', total: 0.4 },
]

export function SmallTiles() {
  return (
    <div className="w-full max-w-72">
      <ChartTreemap
        data={STORAGE}
        valueKey="total"
        nameKey="kind"
        format={(gigabytes: number) => `${gigabytes.toLocaleString('pt-BR')} GB`}
        label="Armazenamento usado, por tipo de arquivo"
        className="h-48"
      />
    </div>
  )
}
```

### Soma zero, com o vazio

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

const BY_CATEGORY = [
  { code: 'eletronicos', total: 182_400 },
  { code: 'casa', total: 96_300 },
  { code: 'moda', total: 71_900 },
  { code: 'esporte', total: 38_200 },
  { code: 'beleza', total: 22_700 },
  { code: 'livros', total: 9_800 },
  { code: 'papelaria', total: 3_100 },
]

export function EmptyTreemap() {
  return (
    <div className="w-full max-w-lg">
      <ChartTreemap
        data={BY_CATEGORY.map((row) => ({ ...row, total: 0 }))}
        valueKey="total"
        nameKey="code"
        label="Vendas por categoria"
        empty={{
          title: 'Nenhuma venda no mês',
          description: 'O mapa aparece quando a loja vender o primeiro produto.',
        }}
      />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `data` | `Item[]` | sim |  | - | As categorias. |
| `label` | `string` | sim |  | - | O que o mapa mede, por extenso: vira o nome do grupo e da lista escondida. |
| `nameKey` | `keyof Item & string` | sim |  | - | De onde sai o nome de cada categoria. |
| `valueKey` | `keyof Item & string` | sim |  | - | De onde sai o numero, que vira area. |
| `classNames` | `Partial<Record<"cell" \| "label", string>>` |  |  | - | Classe por parte: `cell`, `label`. |
| `config` | `ChartConfig` |  |  | - | Nome legivel e cor por categoria, o mesmo formato da rosca. |
| `empty` | `{ title: ReactNode; description: ReactNode; action?: ReactNode; icon?: ReactNode; }` |  |  | - | O que aparece no lugar do desenho quando a lista vem vazia ou a soma e zero. |
| `format` | `Format` |  |  | - | Como o numero e escrito, no rotulo, na dica e na lista do leitor de tela. |

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