# Builders (/docs/api/builders)

> Signatures of every builder method. Behaviour is documented on the concept and chart pages linked from each section.

Every method returns a **new** state; none mutates the receiver. Option bags not
listed here are documented on the linked pages.

## Factories [#factories]

```ts
bar(data?): BarState        // visdelta/bar
line(data?): LineState      // visdelta/line
area(data?): AreaState      // visdelta/area
point(data?): PointState    // visdelta/point
unit(data?): UnitState      // visdelta/unit
pie(data?): PieState        // visdelta/pie
```

`data` is rows, `{ values }`, `{ url, type? }` or `{ name }`; see
[Data sources](/docs/concepts/data-and-transforms#data-sources).

## Shared methods [#shared-methods]

Available on every chart state. See [Chart states](/docs/concepts/chart-states)
and [where, highlight and focus](/docs/concepts/selection).

```ts
.data(source)
.x(field, options?)
.y(field, options?)
.channel(name, field, options?)
.color(valueOrField, options?)
.size(field, options?)
.key(fieldOrFields)
.datumKey(fieldOrFields)
.tooltip(fieldOrFields)
.sort(field, 'ascending' | 'descending')
.where(selector)
.highlight(selector, { opacity? })
.focus(selector)
.reset()
.axis(config)
.transition({ duration?, ease?, stagger? })
.repeat(field, { direction?, scales?, columns?, gap?, minWidth?, autoHeight?, minHeight? })
.rows(source?)   // → tidy rows after transforms
.toSpec()        // → detached view spec
```

Unit compact layout bindings and chained setters are equally supported:
`.layout('beeswarm', { x: 'length' })` and `.layout('beeswarm').x('length')`
write the same state. The last explicit binding replaces the complete channel;
omitted layout options preserve it. See [Unit](/docs/charts/unit).

### Chart captions [#chart-captions]

Add titles and subtitles in the surrounding page markup. VisDelta renders the
visualization and its legends; chart captions are not part of chart state.

## Bar [#bar]

See [Bar](/docs/charts/bar).

```ts
.flip(options?)
.breakdown(field?, { layout?, op?, label?, ... })
.rollup(groupby?, options?)
.segment(fieldOrConfig?, config?)
.layout('simple' | 'grouped' | 'stacked', options?)
```

## Line [#line]

See [Line](/docs/charts/line).

```ts
.curve(d3CurveName)
.connect('adjacent' | 'across')
.strokeWidth(number)
.pointSize(number)
.flip(options?)
.breakdown(field, options?)
.rollup({ op? })
```

## Area [#area]

See [Area](/docs/charts/area).

```ts
.baseline(number)
.labels('inside' | 'none')
.curve(d3AreaCurveName)
.connect('adjacent' | 'across')
.breakdown(field, options?)
.layout('stacked' | 'stream', { offset?, order? })
.rollup({ op? })
```

## Point [#point]

See [Point](/docs/charts/point).

```ts
.pointSize(number)
.radius(number)
.connector({ from: number, channel?: 'x' | 'y' })
.connector({ by: string | string[], orderBy?: string })
.flip(options?)
.rollup(groupby, options?)
.breakdown(detail?, options?)
```

## Unit [#unit]

See [Unit](/docs/charts/unit).

```ts
.value(field, { unitValue?, maxUnits? })
.group(field)
.size(number)
.layout('grid' | 'force' | 'bar' | 'beeswarm', { x?, y?, columns? })
.columns(number)
.radius(number) // compatibility alias for size(number)
```

## Pie [#pie]

See [Pie](/docs/charts/pie).

```ts
.value(field, options?)
.label(field)
.labels('inside' | 'outside' | 'none')
.innerRadius(fraction)   // 0 ≤ fraction < 1
```

## Constants [#constants]

| Export                | Entry           | Contents                                     |
| --------------------- | --------------- | -------------------------------------------- |
| `D3_CURVE_NAMES`      | `visdelta/line` | Curve names accepted by `line().curve()`      |
| `D3_AREA_CURVE_NAMES` | `visdelta/area` | Curve names accepted by `area().curve()`      |
| `UNIT_LAYOUTS`        | `visdelta/unit` | Layout names accepted by `unit().layout()`    |


### Channel labels [#channel-labels]

Use `label` in channel options for a field display name, for example
`.x("hp", { label: "Horsepower" })`. An omitted label defaults to the field's
readable name. Compact Unit layout bindings also accept `label` in their channel
objects and remain equivalent to chained `.x()` / `.y()` declarations.

### Readable axis ticks [#readable-axis-ticks]

Default non-log numeric axes use plain decimals for small values and `k`, `m`,
and `b` for thousands, millions, and billions. Temporal scales use UTC calendar
ticks with labels matched to their interval (years, months, dates, or times).
Month and date labels include the year when the domain crosses a year boundary.
An explicit channel `format` overrides the default: numeric channels accept D3
number formats, and temporal channels accept D3 time formats such as `%b %Y`.