# Heatmap

A grid of values read by weight.

- Group: Data
- Import: `import { Heatmap } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/heatmap/
- Related: table, scatter-chart

## When to reach for it

A calendar of activity, a confusion matrix, an hour-by-weekday load. The one form a monochrome system renders better than a chromatic one.

## Accessibility

- A real <table>, not an SVG: the structure a screen reader walks is the structure the eye reads, and every cell announces its own row, column and value.
- Lightness is the only channel that is unambiguously ordered, which is why the standing advice everywhere else is “one hue, light to dark”. Here there is no hue left to get wrong.
- A null is drawn as a dashed outline, never as the palest cell — a missing reading is not a zero.
- Pin domain whenever two grids are compared: on independent domains they look alike and mean different things, which is the one failure a shared legend cannot fix.

## Heatmap

A grid of values read by weight — a calendar of activity, a confusion matrix, an hour-by-weekday load. The one form in the set that a monochrome system renders BETTER than a chromatic one. A heatmap needs a scale whose order the eye can read without consulting a legend, and lightness is the only channel that is unambiguously ordered — which is why "one hue, light to dark" is the standing advice everywhere else, and why the rainbow heatmap is a perennial mistake. Here there is no hue left to get wrong. It is built as a real `<table>` rather than as an SVG, so the structure a screen reader walks is the structure the eye reads: a header row, a header column, and a cell that announces its own value. Nothing else in the package can say that, and nothing else needs to — which is also why this one takes no rendering engine at all.

### Props

- `title` (required) — `string`. What the grid shows. Required, and it names the table.
- `showTitle` — `boolean` default `false`. Prints the title above the grid instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `columns` (required) — `string[]`. Column headers, in the order they should appear.
- `rows` (required) — `string[]`. Row headers, in the order they should appear.
- `cells` (required) — `HeatmapCell[]`.
- `scale` — `HeatmapScale` default `'sequential'`.
- `domain` — `[number, number]`. The domain, as `[min, max]`. Derived from the data when omitted. Pin it whenever two grids are meant to be compared: two heatmaps on independent domains look alike and mean different things, which is the one failure a shared legend cannot fix.
- `formatValue` — `(value: number) => string` default `(value) => value.toLocaleString()`. Formats a value for the cell's announcement and its printed label.
- `showValues` — `boolean` default `false`. Prints the number inside each cell. Only legible on a coarse grid.
- `className` — `string`.

## Example — default

```tsx
import { Heatmap, type HeatmapCell } from '@misoto22/design/charts'

<Heatmap
  title="Commits by weekday and hour"
  showTitle
  description="Darker is busier"
  columns={HOURS}
  rows={DAYS}
  cells={cells}
/>
```

## Example — diverging

```tsx
import { Heatmap, type HeatmapCell } from '@misoto22/design/charts'

<Heatmap
  title="Weekly delta against target"
  showTitle
  description="Zero is the page; darker is further from target in either direction"
  columns={WEEKS}
  rows={TEAMS}
  cells={cells}
  scale="diverging"
  domain={[-40, 40]}
  showValues
/>
```