# Treemap Mark

`treemap` converts flat hierarchy rows into area-proportional leaf rectangles.
It runs after the final plot bounds resolve, so tiling, padding, and labels use
CSS pixels without application-owned coordinates or Cartesian scales.

```ts
import { treemap } from '@tanstack/charts/hierarchy/treemap'

const mark = treemap(rows, {
  path: 'name',
  delimiter: '.',
  value: 'size',
  color: (node) => node.ancestorIds.at(-1) ?? node.id,
  label: 'name',
  inset: 1,
  stroke: '#fff',
})
```

The exact optional subpath keeps hierarchy tiling out of root and ordinary-mark
consumers.

## Hierarchy input

Path input constructs parent-child relationships from a string channel:

```ts
treemap(rows, {
  path: 'name',
  delimiter: '.',
  value: 'size',
})
```

Explicit parent references use `nodeId` because `id` is reserved for the mark:

```ts
treemap(rows, {
  id: 'package-sizes',
  nodeId: 'id',
  parentId: 'parentId',
  value: 'size',
})
```

Path input may omit ancestors. The mark imputes those structural nodes with
`data: null` and empty direct lineage. Duplicate identities, invalid parents,
multiple roots, and cycles throw before rendering. Authored child order is
preserved unless `sort` is supplied.

Path-mode IDs use canonical slash form and `name` is the terminal path segment.
Explicit-parent IDs are opaque, so `name` is the complete authored ID even
when it contains a slash.

## Options

`TreemapPathOptions<TDatum>` and `TreemapParentOptions<TDatum>` form the
`TreemapOptions<TDatum>` union.

| Option                                        | Type                                                    | Default                 | Meaning                                                |
| --------------------------------------------- | ------------------------------------------------------- | ----------------------- | ------------------------------------------------------ |
| `path`                                        | `TransformValue<TDatum, string>`                        | Path mode only          | Full hierarchy path                                    |
| `delimiter`                                   | `string`                                                | `/`                     | One-character path separator                           |
| `nodeId`                                      | `TransformValue<TDatum, string>`                        | Parent mode only        | Explicit node identity                                 |
| `parentId`                                    | `TransformValue<TDatum, string?>`                       | Parent mode only        | Explicit parent identity                               |
| `value`                                       | `TransformValue<TDatum, number?>`                       | Required                | Nonnegative contribution summed through the hierarchy  |
| `method`                                      | `TreemapMethod`                                         | `squarify`              | `squarify`, `binary`, `dice`, `slice`, or `slice-dice` |
| `ratio`                                       | `number`                                                | Golden ratio            | Squarify target aspect ratio, at least `1`             |
| `round`                                       | `boolean`                                               | `false`                 | Round final rectangle coordinates to pixels            |
| `paddingInner`                                | `number`                                                | `0`                     | Pixel gap between adjacent children                    |
| `paddingOuter`                                | `number`                                                | `0`                     | Pixel gap between parent edges and children            |
| `sort`                                        | `TreemapNodeComparator<TDatum>`                         | Authored order          | Sibling comparator over immutable node contexts        |
| `id`                                          | `string`                                                | Layer-derived           | Stable mark identity                                   |
| `color`                                       | `Channel<TreemapNode<TDatum>, ChartKey?>`               | No group                | Node value sent to the color scale                     |
| `fill`, `stroke`                              | `VisualChannel<TreemapNode<TDatum>, string>`            | Resolved color / none   | Per-node paint                                         |
| `fillOpacity`, `strokeOpacity`, `strokeWidth` | `number`                                                | Renderer default        | Rectangle presentation                                 |
| `inset`, `radius`                             | `number`                                                | `0.75` / none           | Painted rectangle inset and corner radius              |
| `label`                                       | `Channel<TreemapNode<TDatum>, string \| number?>`       | None                    | Centered in-cell label                                 |
| `labelFill`                                   | `VisualChannel<TreemapNode<TDatum>, string>`            | Theme foreground        | Label paint                                            |
| `labelFontSize`, `labelFontWeight`            | `number`                                                | `11` / renderer default | Label typography                                       |
| `labelPadding`                                | `number`                                                | `4`                     | Minimum painted pixels around a label                  |
| `states`                                      | `readonly ChartMarkState[]`                             | None                    | Focus-driven rectangle states                          |
| `motion`                                      | `ChartMarkMotionOptions<TreemapNode<TDatum>>['motion']` | None                    | Per-node motion policy                                 |

Nullish values contribute zero. Other values must be nonnegative and finite.
`ratio` is valid only with `squarify`. Padding, inset, and label padding are
nonnegative CSS-pixel values.

## Responsive layout

Treemap row grouping depends on the final plot aspect ratio. The mark sizes the
selected tiler to the resolved inner width and height on every layout pass;
resizing may therefore change rectangle adjacency as well as dimensions.
Coordinates use the screen convention where y increases downward and never
enter a Cartesian scale.

Each pass lays out a private hierarchy copy. Value and path accessors are not
rerun, input rows are not mutated, and repeated compilation at one size is
deterministic. Stateful `resquarify` is intentionally not a method.

## Nodes, labels, and interaction

Only positive-area leaves render. Every rectangle and interaction point carries
one `TreemapNode<TDatum>` with:

- stable `id`, `parentId`, and root-to-parent `ancestorIds`;
- `name`, `depth`, `height`, and `internal` / `external` metadata;
- aggregate `value`;
- the authored `data` row, or `null` for an imputed node; and
- direct `source` and `sourceIndexes` lineage.

Color, paint, state, and label channels receive these nodes. A label is emitted
only when its measured bounds plus `labelPadding` fit inside the painted cell.
This uses the chart host's text measurer when available and the deterministic
scene estimator otherwise.

## Types

The exact entry exports `treemap`, `TreemapMethod`, `TreemapNode`,
`TreemapNodeComparator`, `TreemapPathOptions`, `TreemapParentOptions`, and
`TreemapOptions`.