# LineSeries

Import `LineSeries` and its types from `@pibbl/core/viz`. `LineSeriesProps<D>` requires
`data`, `x`, `y`, `xScale`, and `yScale`. Data is a readonly array or a core signal
of an array. It is not a thunk. Replace arrays to notify consumers; mutation alone
is not reactive.

`LineAccessor<D>` accepts a property key whose value is a `LineCoordinate`, or
`(datum, index, data) => LineCoordinate`. A coordinate is a number, null, or
undefined. Function accessors run during component evaluation; signal reads inside
them belong to the series. Row fields are not recursively unwrapped.

`defined(datum, index, data)` runs before coordinate accessors. False, missing,
NaN, or infinite coordinates split the line into separate runs. Isolated points
paint nothing. Input order is preserved; points are never sorted. `LineCurve`
supports `"linear"` (the default) or a named immutable
[step or monotone definition](/reference/functions/series-curves/).

`LineSeriesStyle` is one static style across every run, with signal-valued whole
style/direct fields: `stroke` (default `#2563eb`), `strokeWidth` (2), `opacity` (1),
`cursor`, and `lineInteractionWidth` (defaults to strokeWidth). Widths must be
finite and nonnegative; opacity is between 0 and 1. No per-datum style callback,
segment styling or fill is implemented here; compose AreaSeries for filled geometry.

One core `Path` owns the complete batch's paint and stroke hit geometry. Ordinary
core event handlers and `pointerEvents` work on that target; gaps remain gaps for
hit testing. There is no nearest-point event enrichment. Applications can compose
inspection or brushing with [`useLinearScale`](/reference/hooks/use-scale/) and core targets.
Wrap the series in a core `Clip` for clipping; scales do not clip automatically.

## Categorical positions

LineSeries, PointSeries, and PlotSeries accept `SeriesAccessor<D>` for x/y. It
extracts `SeriesCoordinate = number | string | null | undefined`. PointScale maps
string and finite numeric categories without coercion: `1` and `"1"` remain
different identities. Unknown categories throw RangeError. Continuous scales
require numbers and reject strings. Null, undefined, and nonfinite numbers create
gaps (or omit isolated marks). BarScale is not a point-position scale.

Source order determines line traversal and is never sorted. PointScale reversal
changes placement without changing datum identity. Domain/data signals and nested
scale lookup retain ordinary reactive ownership. Application code supplies
category inspection through the dedicated `usePointScale` mapping/inversion;
numeric query helpers and `PointAccessor` remain numeric contracts.

`LineAccessor` remains the numeric accessor for area/band bounds and numeric
operations. Neither accessor type can statically prove that an arbitrary scale ID
refers to the matching provider; runtime validation enforces that relationship.

## API details from source

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

### LineSeries

Draws a scaled line through defined data values, leaving gaps for undefined values.

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

Related API: [LineSeries](/reference/components/line-series/), [LineSeriesProps](/reference/components/line-series/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Data, coordinate accessors, scales, and line styling. See [LineSeriesProps](/reference/components/line-series/).

#### Returns

Pibbl nodes drawing the data as a line series.

#### See also

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

[View source — packages/core/src/features/viz/lib/line-series.tsx:24](/source/packages/core/src/features/viz/lib/line-series-tsx/#L24)

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

### LineCoordinate

A numeric series coordinate, or a missing value that can create a gap.

```ts
type LineCoordinate = number | null | undefined
```

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

#### See also

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

[View source — packages/core/src/features/viz/lib/types.ts:387](/source/packages/core/src/features/viz/lib/types-ts/#L387)

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

### LineAccessor

A data property or callback that extracts a numeric series coordinate.

```ts
type LineAccessor<D> = | { [K in keyof D]-?: D[K] extends LineCoordinate ? K : never }[keyof D]
  | ((datum: D, index: number, data: readonly D[]) => LineCoordinate)
```

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

#### Parameters

- **`datum`** — Datum whose coordinate is being read.

- **`index`** — Zero-based index in the source data.

- **`data`** — Complete source data array.

#### Returns

The datum's coordinate, including the supported missing-value sentinel. See
[LineCoordinate](/reference/components/line-series/) .

#### See also

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

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

[PointAccessor](/reference/components/point-series/)

[View source — packages/core/src/features/viz/lib/types.ts:401](/source/packages/core/src/features/viz/lib/types-ts/#L401)

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

### SeriesAccessor

Extracts one position for a line, point, or custom mark.

```ts
type SeriesAccessor<D> = | { [K in keyof D]-?: D[K] extends SeriesCoordinate ? K : never }[keyof D]
  | ((datum: D, index: number, data: readonly D[]) => SeriesCoordinate)
```

Related API: [SeriesAccessor](/reference/components/line-series/), [SeriesCoordinate](/reference/components/line-series/).

#### Parameters

- **`datum`** — Original record.

- **`index`** — Original record index.

- **`data`** — Complete source records.

#### Returns

A numeric or categorical position. See [SeriesCoordinate](/reference/components/line-series/).

#### See also

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

[View source — packages/core/src/features/viz/lib/types.ts:414](/source/packages/core/src/features/viz/lib/types-ts/#L414)

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

### SeriesCoordinate

A numeric or categorical position, or a missing value.

```ts
type SeriesCoordinate = number | string | null | undefined
```

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

#### See also

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

[View source — packages/core/src/features/viz/lib/types.ts:405](/source/packages/core/src/features/viz/lib/types-ts/#L405)

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

### LineCurve

The supported interpolation mode for a line series.

```ts
type LineCurve = "linear" | SeriesCurve
```

Related API: [LineCurve](/reference/components/line-series/), [SeriesCurve](/reference/functions/series-curves/).

#### See also

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

[View source — packages/core/src/features/viz/lib/types.ts:422](/source/packages/core/src/features/viz/lib/types-ts/#L422)

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

### LineSeriesStyle

Supported geometry and presentation properties for LineSeries.

```ts
interface LineSeriesStyle
```

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

#### See also

[StrokeStyle](/reference/types/styles/#strokestyle)

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

[View source — packages/core/src/features/viz/lib/types.ts:429](/source/packages/core/src/features/viz/lib/types-ts/#L429)

#### Properties and methods

<span id="api-LineSeriesStyle-stroke"></span>
<details>
<summary>stroke (optional)</summary>


```ts
readonly stroke?: StrokeStyle | undefined
```

Related API: [StrokeStyle](/reference/types/styles/#strokestyle).

Paint used for the outline. See StrokeStyle.

[View source — packages/core/src/features/viz/lib/types.ts:431](/source/packages/core/src/features/viz/lib/types-ts/#L431)

</details>

<span id="api-LineSeriesStyle-strokeWidth"></span>
<details>
<summary>strokeWidth (optional)</summary>


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

Width of the painted outline. See LineSeriesStyle.

[View source — packages/core/src/features/viz/lib/types.ts:433](/source/packages/core/src/features/viz/lib/types-ts/#L433)

</details>

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


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

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

Opacity of the painted result. See LineSeriesStyle.

[View source — packages/core/src/features/viz/lib/types.ts:435](/source/packages/core/src/features/viz/lib/types-ts/#L435)

</details>

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


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

Cursor shown while this target owns pointer presentation. See LineSeriesStyle.

[View source — packages/core/src/features/viz/lib/types.ts:437](/source/packages/core/src/features/viz/lib/types-ts/#L437)

</details>

<span id="api-LineSeriesStyle-lineInteractionWidth"></span>
<details>
<summary>lineInteractionWidth (optional)</summary>


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

Width used for line hit testing independently of the visible stroke width. See
LineSeriesStyle.

[View source — packages/core/src/features/viz/lib/types.ts:442](/source/packages/core/src/features/viz/lib/types-ts/#L442)

</details>

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

### LineSeriesProps

Authored inputs for LineSeries, including the declared data and presentation options.

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

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

#### See also

[PibblEventHandlers](/reference/types/events/#pibbleventhandlers)

[PibblEventParticipationOptions](/reference/types/events/#pibbleventparticipationoptions)

[SignalValue](/reference/types/signal-inputs/#signalvalue)

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

[ScaleId](/reference/components/scale/)

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

`SignalStyle`

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

[View source — packages/core/src/features/viz/lib/types.ts:456](/source/packages/core/src/features/viz/lib/types-ts/#L456)

#### Properties and methods

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


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

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

Application data supplied to the component or reported by the event. See SignalValue.

[View source — packages/core/src/features/viz/lib/types.ts:461](/source/packages/core/src/features/viz/lib/types-ts/#L461)

</details>

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


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

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

Property key or callback extracting the horizontal domain coordinate. See LineAccessor.

[View source — packages/core/src/features/viz/lib/types.ts:463](/source/packages/core/src/features/viz/lib/types-ts/#L463)

</details>

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


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

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

Property key or callback extracting the vertical domain coordinate. See LineAccessor.

[View source — packages/core/src/features/viz/lib/types.ts:465](/source/packages/core/src/features/viz/lib/types-ts/#L465)

</details>

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


```ts
readonly xScale: ScaleId
```

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

The scale used to map horizontal data coordinates. See ScaleId.

[View source — packages/core/src/features/viz/lib/types.ts:467](/source/packages/core/src/features/viz/lib/types-ts/#L467)

</details>

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


```ts
readonly yScale: ScaleId
```

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

The scale used to map vertical data coordinates. See ScaleId.

[View source — packages/core/src/features/viz/lib/types.ts:469](/source/packages/core/src/features/viz/lib/types-ts/#L469)

</details>

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


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

Returns whether a datum contributes drawable or queryable coordinates. See
LineSeriesProps.

##### Parameters

- **`datum`** — Datum to test.

- **`index`** — Zero-based index in the source data.

- **`data`** — Complete source data array.

##### Returns

Whether this datum should participate in the series or query.

[View source — packages/core/src/features/viz/lib/types.ts:478](/source/packages/core/src/features/viz/lib/types-ts/#L478)

</details>

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


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

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

Interpolation mode used to connect successive defined samples. See LineCurve.

[View source — packages/core/src/features/viz/lib/types.ts:480](/source/packages/core/src/features/viz/lib/types-ts/#L480)

</details>

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


```ts
readonly style?: SignalValue<Readonly<{ readonly stroke?: SignalValue<StrokeStyle | undefined>; readonly strokeWidth?: SignalValue<number | undefined>; readonly opacity?: SignalValue<number | undefined>; readonly cursor?: SignalValue<string | undefined>; readonly lineInteractionWidth?: SignalValue<number | undefined>; }>> | undefined
```

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

Declared presentation and layout properties. See SignalValue, SignalStyle,
LineSeriesStyle.

[View source — packages/core/src/features/viz/lib/types.ts:485](/source/packages/core/src/features/viz/lib/types-ts/#L485)

</details>

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

- [Line series](/minimal-examples/viz/lines/): Plot readings with a nullable gap and a scale-adjusted marker. [Plain source](/minimal/viz/lines.tsx)
- [Categorical series](/minimal-examples/viz/categories/): Map original category identities with line and point marks. [Plain source](/minimal/viz/categories.tsx)
## Documentation version

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