# Types (/docs/api/types)

> The public types you are most likely to read or annotate, generated from the library's TypeScript source.

The tables on this page are generated at build time from the TypeScript source,
so they always match the published declarations.

## StateChange [#statechange]

`delta().stateChanges` is a `StateChange[]`. It is a discriminated union on
`category`:

```ts
type StateChange =
  | { category: 'data'; action: 'add' | 'remove' | 'update' }
  | {
      category: 'grain';
      action: 'split' | 'merge' | 'reaggregate' | 'change-reducer';
      previous: GrainDescription;
      next: GrainDescription;
    }
  | { category: 'encoding'; action: 'bind' | 'unbind' | 'remap'; channel: string }
  | { category: 'coordinate'; action: 'rescale' | 'reorient'; channel?: 'x' | 'y' }
  | { category: 'layout'; action: 'reorder' | 'rearrange' | 'reconnect' }
  | { category: 'attention'; action: 'enter' | 'exit' | 'shift'; target: 'focus' | 'highlight' }
  | { category: 'appearance'; action: 'restyle' | 'reshape'; property: string };
```

Narrow on `category` to read the extra fields:

```ts
for (const change of delta(from, to).stateChanges) {
  if (change.category === 'encoding') console.log(change.channel);
  if (change.category === 'grain') console.log(change.previous.groupby, '→', change.next.groupby);
}
```

### GrainDescription [#graindescription]

### GrainDescription

| Prop         | Type     | Description                            |
| ------------ | -------- | -------------------------------------- |
| `groupby`    | `array`  |                                        |
| `measures`   | `array`  |                                        |
| `unitValue?` | `number` | Quantity represented by one Unit mark. |

### GrainMeasure [#grainmeasure]

### GrainMeasure

| Prop    | Type     | Description |
| ------- | -------- | ----------- |
| `op`    | `string` |             |
| `field` | `union`  |             |
| `as`    | `union`  |             |

## VisualizationWarning [#visualizationwarning]

Returned by `visualizationWarnings()` and dispatched in `visdelta:warnings`
events. See [Visualization warnings](/docs/guides/warnings).

### VisualizationWarning

Advisory only: never changes state, validity or transition planning.

| Prop         | Type                    | Description                                     |
| ------------ | ----------------------- | ----------------------------------------------- |
| `code`       | `string`                |                                                 |
| `severity`   | `"warning"`             |                                                 |
| `message`    | `string`                |                                                 |
| `suggestion` | `string`                |                                                 |
| `source?`    | `string`                | Optional design-guide source for this advisory. |
| `field?`     | `string`                |                                                 |
| `evidence`   | `Record<string, union>` |                                                 |

## ChannelSpec [#channelspec]

The options accepted by `.x()`, `.y()`, `.color()`, `.size()` and `.channel()`.

### ChannelSpec

| Prop         | Type                      | Description                                                                   |
| ------------ | ------------------------- | ----------------------------------------------------------------------------- |
| `field?`     | `string`                  |                                                                               |
| `type?`      | `union`                   |                                                                               |
| `label?`     | `string`                  | Display name for this channel.                                                |
| `title?`     | ``                        | Channel display names use label.                                              |
| `format?`    | `string`                  | D3 number format for quantitative axes, or UTC time format for temporal axes. |
| `aggregate?` | `union`                   |                                                                               |
| `timeUnit?`  | `string`                  |                                                                               |
| `value?`     | `union`                   |                                                                               |
| `sort?`      | `union`                   |                                                                               |
| `domain?`    | `array`                   |                                                                               |
| `scheme?`    | `string`                  | Named d3-scale-chromatic scheme, for example "Tableau10" or "Viridis".        |
| `scale?`     | `Record<string, unknown>` |                                                                               |
| `bin?`       | `union`                   |                                                                               |

## FacetLayout [#facetlayout]

Options for `.repeat()` and `smallMultiples()`. See [Small multiples](/docs/charts/repeat).

### FacetLayout

| Prop          | Type     | Description |
| ------------- | -------- | ----------- |
| `columns?`    | `number` |             |
| `gap?`        | `number` |             |
| `minWidth?`   | `number` |             |
| `direction?`  | `union`  |             |
| `scales?`     | `union`  |             |
| `autoHeight?` | `union`  |             |
| `minHeight?`  | `number` |             |

## ChartStyleDefinition [#chartstyledefinition]

The input to `defineChartStyle()`. See [Styling and themes](/docs/guides/styling).

### ChartStyleDefinition

| Prop              | Type              | Description |
| ----------------- | ----------------- | ----------- |
| `key`             | `string`          |             |
| `tickSpacing?`    | `Partial<object>` |             |
| `edgeTitleInset?` | `Partial<object>` |             |
| `legendInset?`    | `Partial<object>` |             |
| `legendPosition?` | `union`           |             |
| `plot?`           | `object`          |             |
| `axisTitle?`      | `function`        |             |

## DeclarationPlanOptions [#declarationplanoptions]

### DeclarationPlanOptions

| Prop               | Type     | Description                                                 |
| ------------------ | -------- | ----------------------------------------------------------- |
| `maxSearchStates?` | `number` | Bound route search by distinct complete declaration states. |