# Treemap chart

> Parts of a whole drawn as rectangles whose areas follow their values.

## Anatomy

A `<figure class="treemap-chart">` draws each row of a `<table>` as a rectangle whose area follows its value, together filling the plot.

The table takes the same shape as a [pie chart](pie-chart.html)'s: the first column names each row and the second holds its value. Each rectangle's share of the plot is its row's share of the total, and its name and value are written inside it. A treemap keeps many parts readable where a pie runs out of room for slices. To compare a few values against each other, use a [bar chart](bar-chart.html).

```
<figure class="treemap-chart">
  <figcaption>Budget by team</figcaption>
  <table>
    <thead>
      <tr><th>Team</th><th>Budget</th></tr>
    </thead>
    <tbody>
      <tr><th>Engineering</th><td>$600,000</td></tr>
      <tr><th>Research</th><td>$300,000</td></tr>
      <!-- One row per team -->
    </tbody>
  </table>
</figure>
```

## Layout

The layout is squarified. Rows are placed from the largest value to the smallest, equal values in table order, and each strip of rectangles is chosen to keep them near square for the plot's shape. The largest starts at the top inline-start corner, so a right-to-left page mirrors the layout. A rectangle's place follows its value, not its row, and the layout follows the plot when it changes shape.

A rectangle too small to hold its name and value shows neither; the tooltip names it. Long names end in an ellipsis. Rectangles take six colors in table order, then repeat, so neighbours can share a color past the sixth row.

## Values and gaps

Cells read as in the [column chart](column-chart.html): `data-value` wins over the text, and the text may carry a currency or percent sign and grouping commas around one number. A zero, negative or non-numeric cell draws no rectangle and adds nothing to the total. Its row stays in the table. Further value columns add lines to the tooltip.

A gap of `--md-comp-treemap-chart-gap` parts neighbours. It is drawn inside each rectangle's area, so the areas stay exact.

## Accessibility

The table is the chart's text alternative. Give it a header row and a header cell per row, and name the chart with a `<figcaption>`. The drawn rectangles and their text are hidden from assistive technology.

The plot is one Tab stop named by the caption. Keyboard focus shows the first row with a rectangle. The arrow keys step through the rows with a rectangle in table order: right and down go to the next, left and up to the one before. Home and End jump to the first and last, and Escape hides the tooltip. The arrows keep this meaning in a right-to-left page, since table order is not a direction on screen. The pointer and a tap show the rectangle under them. The tooltip is a polite live region, so a screen reader hears the row, its value and its share of the whole as it moves. A ring in the gap marks the highlighted rectangle, and in forced colors each rectangle keeps an edge.

## JavaScript

`AutoInit()` starts every `.treemap-chart`. To start one yourself, call `TreemapChart.init`. After changing its table, call `update()` to redraw it in place, or put `data-watch` on the figure and it redraws itself. Rectangles take their new places at once. It has the line chart's methods; the `min` and `max` options do not apply.

```
const chart = Expressive.TreemapChart.init(document.querySelector('.treemap-chart'));
chart.show(2);   // highlight the third row, or the next one with a rectangle; -1 hides the tooltip
chart.update();  // redraw from the table; focus and the highlighted row stay
chart.destroy(); // remove the drawing and show the table again
```

## Tokens

Override these on the `.treemap-chart`.

| Token | Default |
| --- | --- |
| `--md-comp-treemap-chart-height` | 240px |
| `--md-comp-treemap-chart-gap` | 4px between neighbours |
| `--md-comp-treemap-chart-color-1` … `-6` | `primary`, `tertiary`, `secondary`, `on-surface-variant`, then `primary-container` and `tertiary-container` deepened toward `on-surface` |
| `--md-comp-treemap-chart-on-color-1` … `-6` | `on-primary`, `on-tertiary`, `on-secondary`, `surface`, `surface`, `surface` |

For a selective Sass build, include `"treemap-chart"` in `$components`.