# AreaSeries

Import from `@pibbl/core/viz`. `AreaSeries<D>(props: AreaSeriesProps<D>): PibblNode`
adds scale-derived closed geometry to ordinary Canvas fill. It owns one batched
core Path. Compose LineSeries for the observed outline; layout, clipping,
annotations, and inspection stay application-owned.

Required inputs are `data`, `x`, `y`, `xScale`, `yScale`, and `baseline`.
Data is a readonly array or signal of an array. Accessors follow
[LineSeries](/reference/components/line-series/): a numeric field key or callback
`(datum, index, data) => number | null | undefined`. Both named scales must be
continuous (linear, UTC, log, or symlog). The finite numeric baseline is required
and maps through the y scale; log baselines must be positive. No implicit zero,
clamping, sorting, aggregation, or clipping occurs.

`defined?` runs before accessors. Excluded, missing, and nonfinite coordinates
split runs. Empty and isolated single-point runs draw no area. A run follows
observations in authored order, then closes from its last x to the baseline and
back to its first x. Duplicate x values produce vertical segments; baseline
crossings and reversed domains/ranges retain that geometry. Self-intersections
use Canvas's nonzero fill rule. These are geometric fills, not integrals or
additional observations. Query the original observations for inspection.

`baseline`, data, whole style, and direct style fields accept signals. Reads in
accessors track the component; replace arrays to update. No subscriptions or
resources survive removal/disposal. `style.fill` defaults to `#2563eb`,
`style.opacity` to `0.2`, and `style.cursor` is optional. Opacity must be finite
between 0 and 1; fill uses core paint values. No stroke or per-row styling is
accepted. Invalid arrays/styles throw TypeError; invalid baseline/opacity or
scale mapping throws RangeError; unknown/mismatched scales follow scale errors.

Normal core event props and pointer participation apply to the whole filled
Path. It participates by default; use `pointerEvents="none"` for decorative fill
under an inspection target. Gaps do not acquire filled hit geometry. Coordinates
are local logical pixels after mapping; core transforms and explicit Clip apply
normally. No margins or minimum layout size are allocated by the series.

Try [the NOAA area example](/playground/#/examples/composition/viz-area-basics): change the
reference baseline, deliberately omit June, and inspect with touch or keyboard.
The fill is distance above that reference, not cumulative emissions.

Optional `curve` accepts the [named step or monotone definitions](/reference/functions/series-curves/);
omission and `"linear"` retain straight segments.

## API details from source

<span id="api-AreaSeries"></span>

### AreaSeries

Draws each contiguous observed run as a filled polygon closed to an explicit baseline.

Missing, non-finite, and excluded coordinates split runs. A lone observation has no area.
The component owns one ordinary Path target, so event participation follows the
standard Path defaults; callers may wrap it in `Clip` when clipping is needed.

```ts
AreaSeries: <D>({ data: dataInput, x: xInput, y: yInput, xScale: xId, yScale: yId, baseline: baselineInput, defined, curve, style: styleInput, ...eventProps }: AreaSeriesProps<D>) => JSX.Element
```

Related API: [AreaSeries](/reference/components/area-series/), [AreaSeriesProps](/reference/components/area-series/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Data, coordinate accessors, continuous scales, baseline, and presentation.

#### Returns

A Pibbl path node containing all drawable area runs.

#### Throws

When `data` is not an array, the baseline is not finite, or presentation is invalid.

#### See also

[AreaSeriesProps](/reference/components/area-series/)

[View source — packages/core/src/features/viz/lib/area-series.tsx:105](/source/packages/core/src/features/viz/lib/area-series-tsx/#L105)

<span id="api-AreaSeriesProps"></span>

### AreaSeriesProps

Authored inputs for AreaSeries.

The data, coordinate accessors, scales, and defined predicate use the same
contract as LineSeriesProps. Each contiguous run of at least two
valid observations is closed to `baseline` in data space.

```ts
interface AreaSeriesProps<D> extends PibblEventHandlers, PibblEventParticipationOptions
```

Related API: [AreaSeriesProps](/reference/components/area-series/), [PibblEventHandlers](/reference/types/events/#pibbleventhandlers), [PibblEventParticipationOptions](/reference/types/events/#pibbleventparticipationoptions).

#### See also

[LineSeriesProps](/reference/components/line-series/)

[AreaSeriesStyle](/reference/components/area-series/)

[View source — packages/core/src/features/viz/lib/area-series.tsx:47](/source/packages/core/src/features/viz/lib/area-series-tsx/#L47)

#### Properties and methods

<span id="api-AreaSeriesProps-data"></span>
<details>
<summary>data</summary>


```ts
readonly data: SignalValue<readonly D[]>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Application data supplied directly or through a signal.

[View source — packages/core/src/features/viz/lib/area-series.tsx:50](/source/packages/core/src/features/viz/lib/area-series-tsx/#L50)

</details>

<span id="api-AreaSeriesProps-x"></span>
<details>
<summary>x</summary>


```ts
readonly x: LineAccessor<D>
```

Related API: [LineAccessor](/reference/components/line-series/).

Property key or callback extracting the horizontal coordinate.

[View source — packages/core/src/features/viz/lib/area-series.tsx:52](/source/packages/core/src/features/viz/lib/area-series-tsx/#L52)

</details>

<span id="api-AreaSeriesProps-y"></span>
<details>
<summary>y</summary>


```ts
readonly y: LineAccessor<D>
```

Related API: [LineAccessor](/reference/components/line-series/).

Property key or callback extracting the vertical coordinate.

[View source — packages/core/src/features/viz/lib/area-series.tsx:54](/source/packages/core/src/features/viz/lib/area-series-tsx/#L54)

</details>

<span id="api-AreaSeriesProps-xScale"></span>
<details>
<summary>xScale</summary>


```ts
readonly xScale: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

Continuous scale used to map horizontal data coordinates.

[View source — packages/core/src/features/viz/lib/area-series.tsx:56](/source/packages/core/src/features/viz/lib/area-series-tsx/#L56)

</details>

<span id="api-AreaSeriesProps-yScale"></span>
<details>
<summary>yScale</summary>


```ts
readonly yScale: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

Continuous scale used to map vertical data coordinates and baseline.

[View source — packages/core/src/features/viz/lib/area-series.tsx:58](/source/packages/core/src/features/viz/lib/area-series-tsx/#L58)

</details>

<span id="api-AreaSeriesProps-defined"></span>
<details>
<summary>defined (optional)</summary>


```ts
readonly defined?: ((datum: D, index: number, data: readonly D[]) => boolean) | undefined
```

Selects records that participate in an observed run.

[View source — packages/core/src/features/viz/lib/area-series.tsx:60](/source/packages/core/src/features/viz/lib/area-series-tsx/#L60)

</details>

<span id="api-AreaSeriesProps-curve"></span>
<details>
<summary>curve (optional)</summary>


```ts
readonly curve?: LineCurve | undefined
```

Related API: [LineCurve](/reference/components/line-series/).

Curve used to connect successive observed samples.

[View source — packages/core/src/features/viz/lib/area-series.tsx:62](/source/packages/core/src/features/viz/lib/area-series-tsx/#L62)

</details>

<span id="api-AreaSeriesProps-baseline"></span>
<details>
<summary>baseline</summary>


```ts
readonly baseline: SignalValue<number>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Finite data-space value to which each observed run closes.

[View source — packages/core/src/features/viz/lib/area-series.tsx:64](/source/packages/core/src/features/viz/lib/area-series-tsx/#L64)

</details>

<span id="api-AreaSeriesProps-style"></span>
<details>
<summary>style (optional)</summary>


```ts
readonly style?: SignalValue<Readonly<{ readonly fill?: SignalValue<FillStyle | undefined>; readonly opacity?: SignalValue<number | undefined>; readonly cursor?: SignalValue<string | undefined>; }>> | undefined
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue), [FillStyle](/reference/types/styles/#fillstyle), [opacity](/reference/types/filters/#opacity).

Shared area presentation. Individual datum styling is not supported.

[View source — packages/core/src/features/viz/lib/area-series.tsx:66](/source/packages/core/src/features/viz/lib/area-series-tsx/#L66)

</details>

<span id="api-AreaSeriesProps-pointerEvents"></span>
<details>
<summary>pointerEvents (optional)</summary>


```ts
readonly pointerEvents?: PibblPointerEvents | undefined
```

Related API: [PibblPointerEvents](/reference/types/events/#pibblpointerevents).

Whether this content participates in pointer targeting. See PibblPointerEvents.

[View source — packages/core/src/lib/events/types.ts:126](/source/packages/core/src/lib/events/types-ts/#L126)

</details>

<span id="api-AreaSeriesStyle"></span>

### AreaSeriesStyle

Presentation properties for an AreaSeries.

```ts
interface AreaSeriesStyle
```

Related API: [AreaSeriesStyle](/reference/components/area-series/).

#### See also

[FillStyle](/reference/types/styles/#fillstyle)

[AreaSeriesProps](/reference/components/area-series/)

[View source — packages/core/src/features/viz/lib/area-series.tsx:28](/source/packages/core/src/features/viz/lib/area-series-tsx/#L28)

#### Properties and methods

<span id="api-AreaSeriesStyle-fill"></span>
<details>
<summary>fill (optional)</summary>


```ts
readonly fill?: FillStyle | undefined
```

Related API: [FillStyle](/reference/types/styles/#fillstyle).

Paint used for the area interior.

[View source — packages/core/src/features/viz/lib/area-series.tsx:30](/source/packages/core/src/features/viz/lib/area-series-tsx/#L30)

</details>

<span id="api-AreaSeriesStyle-opacity"></span>
<details>
<summary>opacity (optional)</summary>


```ts
readonly opacity?: number | undefined
```

Related API: [opacity](/reference/types/filters/#opacity).

Opacity of the painted area, from zero through one.

[View source — packages/core/src/features/viz/lib/area-series.tsx:32](/source/packages/core/src/features/viz/lib/area-series-tsx/#L32)

</details>

<span id="api-AreaSeriesStyle-cursor"></span>
<details>
<summary>cursor (optional)</summary>


```ts
readonly cursor?: string | undefined
```

Cursor shown while the area target owns pointer presentation.

[View source — packages/core/src/features/viz/lib/area-series.tsx:34](/source/packages/core/src/features/viz/lib/area-series-tsx/#L34)

</details>

## Implementation guidance for agents

Read the [Data visualization companion](/agents/topics/visualization/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Area and gaps](/minimal-examples/viz/area/): Fill runs to an explicit reference baseline. [Plain source](/minimal/viz/area.tsx)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.