# Series curve definitions
Import from `@pibbl/core/viz`:
- `monotoneX(): SeriesCurve`: smooth cubic connections preserving each adjacent pair's extrema.
- `stepBefore(): SeriesCurve`: jump to the next y at the preceding x, then travel horizontally.
- `stepAfter(): SeriesCurve`: hold the preceding y until the next x, then jump.
- `stepMidpoint(): SeriesCurve`: hold until the midpoint between x positions, jump, then hold the next y.
Each returns one immutable opaque definition with the same fixed contract. It
accepts no options and owns no resources. No generic family selector or custom
curve implementation API is exposed. Pass a definition as `curve` on LineSeries,
AreaSeries, or IntervalBandSeries. Omission and `curve="linear"` preserve straight
segments. Definitions are ordinary values; read a signal in the component to
select a definition reactively. A signal is not itself a curve definition.
Forged objects and unknown strings throw TypeError, including for empty data.
Algorithms operate on mapped local coordinates and preserve source order,
observed endpoints, missing runs, transforms, and clipping. Step definitions also
preserve duplicate x values.
Before/after refer to traversal order even for descending x. Midpoint means
halfway in mapped coordinates (so it is a geometric midpoint on nonlinear scales).
An interval's two boundaries use the same jump positions; reversing its lower
outline does not reverse the chosen transition policy. Step strategies cannot
invent intermediate extrema or invert an ordered interval.
A vertical jump contains both adjacent y values geometrically. Inspection in
these demos selects an original observation (nearest x; ties follow source order),
not a value inferred from the jump. `interpolateX` remains a linear data estimate;
it does not silently acquire the displayed curve's semantics. No added point
is claimed to be a measurement. Use ordinary observed-data inspection unless
an application explicitly defines a different estimate.
The [policy-rate steps example](/playground/#/examples/composition/viz-policy-steps) uses real
Federal Reserve target ranges. Only stepAfter represents policy held until the
next effective date; other choices visibly demonstrate geometry, not historical
policy paths. Date positions have day precision, not intraday timing.
## Monotone x
`monotoneX()` requires strictly ascending or strictly descending mapped x within
each finite run. Duplicate x or a change in direction throws RangeError; data is
never sorted. A collapsed x range is therefore invalid for a multi-point run.
Flat y intervals stay flat and local extrema have zero slope. With nonlinear
scales, the smooth shape is defined in mapped coordinates. No smoothing crosses
a missing-value gap.
Interval bands validate the difference between generated cubic boundaries at
endpoints and all interior derivative roots. If smooth boundaries cross, the band
throws RangeError rather than silently drawing an inverted interval. Comparison
uses a 64-machine-epsilon tolerance relative to the segment's largest boundary
difference control, solely for floating-point tangency error; geometry is not adjusted. Use linear
or step connections for data whose independent smooth bounds cross.
The [monthly CO₂ example](/playground/#/examples/composition/viz-monotone-climate) compares
linear and monotone line/area geometry with observed-value inspection. Smoothing
does not create measurements, estimates of uncertainty, or new query semantics.
## API details from source
### SeriesCurve
An opaque immutable definition controlling how a series connects adjacent observations.
Obtain a definition from one of the named curve factories. Definitions intentionally expose
no algorithm selector or custom callback surface.
```ts
interface SeriesCurve
```
Related API: [SeriesCurve](/reference/functions/series-curves/).
#### See also
[LineSeriesProps](/reference/components/line-series/)
[View source — packages/core/src/features/viz/lib/curve-definition.ts:36](/source/packages/core/src/features/viz/lib/curve-definition-ts/#L36)
### stepBefore
Returns the immutable definition that jumps to the next value at the prior x coordinate.
```ts
stepBefore: () => SeriesCurve
```
Related API: [stepBefore](/reference/functions/series-curves/), [SeriesCurve](/reference/functions/series-curves/).
#### Returns
The named [SeriesCurve](/reference/functions/series-curves/) definition.
[View source — packages/core/src/features/viz/lib/step-curves.ts:55](/source/packages/core/src/features/viz/lib/step-curves-ts/#L55)
### stepAfter
Returns the immutable definition that holds the prior value until the next x coordinate.
```ts
stepAfter: () => SeriesCurve
```
Related API: [stepAfter](/reference/functions/series-curves/), [SeriesCurve](/reference/functions/series-curves/).
#### Returns
The named [SeriesCurve](/reference/functions/series-curves/) definition.
[View source — packages/core/src/features/viz/lib/step-curves.ts:64](/source/packages/core/src/features/viz/lib/step-curves-ts/#L64)
### stepMidpoint
Returns the immutable definition that places each value transition halfway between x values.
```ts
stepMidpoint: () => SeriesCurve
```
Related API: [stepMidpoint](/reference/functions/series-curves/), [SeriesCurve](/reference/functions/series-curves/).
#### Returns
The named [SeriesCurve](/reference/functions/series-curves/) definition.
[View source — packages/core/src/features/viz/lib/step-curves.ts:73](/source/packages/core/src/features/viz/lib/step-curves-ts/#L73)
### monotoneX
Returns the immutable monotone-X cubic Hermite definition.
It uses weighted harmonic interior slopes and limited one-sided endpoint slopes, preserving every observation,
flat segment, and local extremum without sorting data. Each run must have strictly ascending
or strictly descending x coordinates.
```ts
monotoneX: () => SeriesCurve
```
Related API: [monotoneX](/reference/functions/series-curves/), [SeriesCurve](/reference/functions/series-curves/).
#### Returns
The named [SeriesCurve](/reference/functions/series-curves/) definition.
[View source — packages/core/src/features/viz/lib/monotone-curve.ts:86](/source/packages/core/src/features/viz/lib/monotone-curve-ts/#L86)
## 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
- [Named step definitions](/minimal-examples/viz/steps/): Compare before, midpoint, and after jumps between the same endpoints. [Plain source](/minimal/viz/steps.tsx)
- [Monotone observations](/minimal-examples/viz/monotone/): Smooth measured observations without introducing extrema. [Plain source](/minimal/viz/monotone.tsx)
## Documentation version
Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.