# Heatmap

A grid of values read by weight.

- Group: Data
- Import: `import { Heatmap } from '@misoto22/folio/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.

## Anatomy

- **Figure caption** (required) — title in a figcaption, hidden from sight unless showTitle prints it above the grid with description under it. The same string is also the table’s own sr-only caption, so the grid is named on the way in and again from the table.
- **Column headers** (required) — One th scope="col" per entry in columns, in the order given, preceded by an sr-only corner cell reading “Row” so the header line has something standing over the row labels.
- **Row headers** (required) — One th scope="row" per entry in rows — end-aligned mono at --chart-axis, so every cell can be traced back to the pair of labels that names it.
- **Cell** (required) — A td whose background is a color-mix of --series-1 into --chart-surface at the value’s position in the domain. Continuous rather than stepped, because banding a ramp invents boundaries the data does not have, and 2px of border-spacing between cells is what makes two neighbouring weights countable.
- **Missing cell** — What a null draws — and what a row and column pair absent from cells draws too: a dashed --rule outline over the page, announcing “no data” instead of a number.
- **Printed value** — formatValue inside the cell. Visible with showValues, otherwise sr-only and un-hidden again under forced colours, where the wash that WAS the encoding has been remapped away.

## Best practices

### Do

- Switch scale to diverging the moment the values cross zero. sequential ramps on POSITION in the domain, so on a grid of changes the deepest fall is the palest cell and the biggest rise the darkest; diverging ramps on distance from the midpoint instead, which is the read a delta actually wants.
- Pin domain when one cell is an order of magnitude clear of the rest. The derived domain runs from zero — or the lowest value, when that is negative — to the highest, so a single 10,000 among readings of 5 to 40 puts every other cell inside the first half percent of the ramp, and forty distinct numbers render as one dark square on a blank grid.
- Spell a cell’s row and column exactly as they appear in rows and columns: cells are looked up by that pair, so an unmatched entry draws nothing at all. It no longer counts toward the derived domain either — a typo used to stretch the ramp with a value that appeared nowhere on the grid, pushing every drawn cell into the first fraction of it.
- Take the contrast trade knowingly when showValues goes on. The wash is capped at 35 percent of the ramp so one ink colour clears 4.5:1 on every cell — the ORDER of the cells survives untouched, the spread between them narrows, and the printed numbers become the thing carrying the detail.

### Don’t

- Do not let a pipeline fill gaps with zero before the grid sees them. A null is drawn as a dashed outline and announced as no data, and a zero is drawn as the palest cell on the ramp — so substituting one for the other turns an outage into a quiet hour, and nothing on the grid says which it was.
- Do not expect a reader to recover a figure from the wash. There is no legend and no step: weight orders the cells and never states one. The forced-colours fallback un-hides the numbers because the background has stopped existing there, which is a rescue for a remapped ground rather than a substitute for showValues on a grid whose exact figures matter.

## 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, cell: HeatmapCell) => string` default `(value) => value.toLocaleString()`. Formats a value for the cell's announcement and its printed label. The cell is handed over as well, so a grid whose columns are not self-describing can name the reading rather than only the number. A calendar is the case that needs it: two days with the same count are two different readings, and the row and column headers a cell is announced with — "Mon" and a month name over a block of five weeks — do not say which day it was.
- `showValues` — `boolean` default `false`. Prints the number inside each cell. Only legible on a coarse grid.
- `className` — `string`.
- `empty` — `ChartEmptyProps`. What the grid shows when it has no rows or no columns to draw. A heatmap with no headers renders as a caption over nothing, which reads as a grid that failed to load rather than as one with nothing in it.

## Example — default

```tsx
import { Heatmap, type HeatmapCell } from '@misoto22/folio/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/folio/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
/>
```

## Example — shared domain

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

<div className="grid w-full gap-8 lg:grid-cols-2">
  <Heatmap
    title="Median queue wait — Sydney"
    showTitle
    description="Darker is a longer wait"
    columns={SHIFTS}
    rows={DAYS}
    cells={sydney}
    domain={WAIT}
    formatValue={asDuration}
  />
  <Heatmap
    title="Median queue wait — Frankfurt"
    showTitle
    description="Same scale, so the two grids can be compared"
    columns={SHIFTS}
    rows={DAYS}
    cells={frankfurt}
    domain={WAIT}
    formatValue={asDuration}
  />
</div>
```