# IntervalBandSeries

Import from `@pibbl/core/viz`.
`IntervalBandSeries<D>(props: IntervalBandSeriesProps<D>): PibblNode` fills between
two data-derived bounds. Unlike ReferenceBand, the bounds may change at every
observation. It does not invent a midpoint, aggregate data, or infer uncertainty.

Required inputs: `data`, `x`, `lower`, `upper`, `xScale`, and `yScale`. Data accepts
a readonly array or signal. Each accessor is a numeric field key or callback
`(datum, index, data) => number | null | undefined`. Both named scales must be
continuous: linear, UTC, log, or symlog. `defined?` runs before accessors. Missing,
nonfinite, or excluded coordinates split runs; at least two matching observations
are needed to draw. Authored order is preserved. Each polygon follows upper
bounds forward and lower bounds backward. Equal bounds produce zero area;
finite `lower > upper` throws RangeError identifying the row rather than silently
swapping their meaning. Invalid log coordinates also throw.

Presentation reuses `AreaSeriesStyle`: fill defaults to `#2563eb`, opacity to
`0.2`, and cursor is optional. Data, whole style, and its direct fields accept
signals; accessors track signal reads normally. Replace arrays to update them.
Opacity must be finite in [0, 1]. Invalid data/paint/style throws TypeError;
invalid opacity or scale mapping throws RangeError. Scale lookup failures follow
normal scale contracts. Unmount/failure cleanup uses the existing runtime.

One ordinary Path owns the complete batch and its filled event geometry. Use
`pointerEvents="none"` when decorative, and inspect the original observations
separately. Core transforms and explicit Clip apply; no layout, clipping,
margins, or scheduler is added. Compose LineSeries for either boundary.
Coordinates are connected by straight segments; these are interpolated edges,
not extra measurements. Unordered x values can self-intersect under Canvas's
nonzero fill rule; no sorting is hidden.

The [daily temperature example](/playground/#/examples/composition/viz-interval-temperature)
uses published NOAA daily minimum and maximum observations. The range describes
a day's temperature extremes, not a confidence or prediction interval.

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-IntervalBandSeries"></span>

### IntervalBandSeries

Draws a filled band between matching lower and upper observations.

Missing, non-finite, and excluded coordinates split runs. A lower value above its upper
value rejects the datum; equal bounds produce zero-area geometry. The component owns one
ordinary Path target, so event participation follows standard Path defaults.

```ts
IntervalBandSeries: <D>({ data: dataInput, x: xInput, lower: lowerInput, upper: upperInput, xScale: xId, yScale: yId, defined, curve, style: styleInput, ...eventProps }: IntervalBandSeriesProps<D>) => JSX.Element
```

Related API: [IntervalBandSeries](/reference/components/interval-band-series/), [IntervalBandSeriesProps](/reference/components/interval-band-series/), [JSX](/reference/overview/).

#### Parameters

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

#### Returns

A Pibbl path node containing all drawable interval-band runs.

#### Throws

When data, presentation, or bounds are invalid.

#### See also

[IntervalBandSeriesProps](/reference/components/interval-band-series/)

[View source — packages/core/src/features/viz/lib/interval-band-series.tsx:93](/source/packages/core/src/features/viz/lib/interval-band-series-tsx/#L93)

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

### IntervalBandSeriesProps

Authored inputs for IntervalBandSeries.

The data, horizontal coordinate, scales, and defined predicate use the same contract as
LineSeriesProps. Each contiguous run of at least two observations draws its upper
boundary forward and lower boundary backward.

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

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

#### See also

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

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

[View source — packages/core/src/features/viz/lib/interval-band-series.tsx:35](/source/packages/core/src/features/viz/lib/interval-band-series-tsx/#L35)

#### Properties and methods

<span id="api-IntervalBandSeriesProps-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/interval-band-series.tsx:38](/source/packages/core/src/features/viz/lib/interval-band-series-tsx/#L38)

</details>

<span id="api-IntervalBandSeriesProps-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/interval-band-series.tsx:40](/source/packages/core/src/features/viz/lib/interval-band-series-tsx/#L40)

</details>

<span id="api-IntervalBandSeriesProps-lower"></span>
<details>
<summary>lower</summary>


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

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

Property key or callback extracting the lower bound.

[View source — packages/core/src/features/viz/lib/interval-band-series.tsx:42](/source/packages/core/src/features/viz/lib/interval-band-series-tsx/#L42)

</details>

<span id="api-IntervalBandSeriesProps-upper"></span>
<details>
<summary>upper</summary>


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

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

Property key or callback extracting the upper bound.

[View source — packages/core/src/features/viz/lib/interval-band-series.tsx:44](/source/packages/core/src/features/viz/lib/interval-band-series-tsx/#L44)

</details>

<span id="api-IntervalBandSeriesProps-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/interval-band-series.tsx:46](/source/packages/core/src/features/viz/lib/interval-band-series-tsx/#L46)

</details>

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


```ts
readonly yScale: ScaleId
```

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

Continuous scale used to map both data bounds.

[View source — packages/core/src/features/viz/lib/interval-band-series.tsx:48](/source/packages/core/src/features/viz/lib/interval-band-series-tsx/#L48)

</details>

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


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

Selects records that participate in a matching-bounds run.

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

</details>

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


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

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

Curve used to connect successive matching bounds.

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

</details>

<span id="api-IntervalBandSeriesProps-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 band presentation. Individual datum styling is not supported.

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

</details>

<span id="api-IntervalBandSeriesProps-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>

## 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

- [Observed interval band](/minimal-examples/viz/interval-band/): Map paired published lower/upper observations into a filled band. [Plain source](/minimal/viz/interval-band.tsx)
## Documentation version

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