# PlotSeries

Import from `@pibbl/core/viz`. Supply `data`, numeric `x`/`y` accessors, `xScale`,
`yScale`, and `render(datum,index,data)`. The callback returns Pibbl nodes around
local `(0,0)` at the mapped point. Invalid coordinates and `defined=false` skip
rows. Custom elements keep ordinary styles, targets, and event handlers.

Use `keyBy="id"` or a key accessor for identity across reorder. Without keyBy,
original source indices are keys. Removing or invalidating a row unmounts it;
returning null retains the row wrapper. Keys normalize as Pibbl string/number keys.

The render callback constructs nodes; hooks belong in returned components.
Its explicit signal reads belong to the row receiver. Series handler props are
structural propagation listeners, with no independent hit geometry. Apply
`pointerEvents`, cursor, and styles to returned elements.

Marks inherit the plot allocation and are translated without resizing or
centering. Percentage lengths retain that allocation until an inner container
changes it. Each row costs its normal component subtree; use PointSeries for
large dot batches, optionally overlaid with a few custom PlotSeries annotations.

Numeric and categorical positions use `SeriesAccessor<D>` with continuous scales
or PointScale. See [categorical position contracts](/reference/components/line-series/).

## API details from source

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

### PlotSeries

Places keyed custom Pibbl subtrees at local data coordinates.

```ts
PlotSeries: <D>({ data: input, x: xInput, y: yInput, xScale: xId, yScale: yId, defined, keyBy, render, ...events }: PlotSeriesProps<D>) => PibblNode
```

Related API: [PlotSeries](/reference/components/plot-series/), [PlotSeriesProps](/reference/components/plot-series/), [PibblNode](/reference/types/elements-components/#pibblnode).

#### Parameters

- **`props`** — Data, coordinate accessors, scales, keys, and per-datum renderer. See
[PlotSeriesProps](/reference/components/plot-series/) .

#### Returns

Pibbl nodes placing each rendered datum at its mapped coordinates. See [PibblNode](/reference/types/elements-components/#pibblnode).

#### See also

[PlotSeriesProps](/reference/components/plot-series/)

[PibblNode](/reference/types/elements-components/#pibblnode)

[View source — packages/core/src/features/viz/lib/plot-series.tsx:33](/source/packages/core/src/features/viz/lib/plot-series-tsx/#L33)

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

### PlotSeriesProps

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

```ts
interface PlotSeriesProps<D> extends PibblEventHandlers
```

Related API: [PlotSeriesProps](/reference/components/plot-series/), [PibblEventHandlers](/reference/types/events/#pibbleventhandlers).

#### See also

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

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

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

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

[PlotKeyAccessor](/reference/components/plot-series/)

[PibblNode](/reference/types/elements-components/#pibblnode)

[PlotSeries](/reference/components/plot-series/)

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

#### Properties and methods

<span id="api-PlotSeriesProps-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/plot-types.ts:36](/source/packages/core/src/features/viz/lib/plot-types-ts/#L36)

</details>

<span id="api-PlotSeriesProps-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 PointAccessor.

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

</details>

<span id="api-PlotSeriesProps-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 PointAccessor.

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

</details>

<span id="api-PlotSeriesProps-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/plot-types.ts:42](/source/packages/core/src/features/viz/lib/plot-types-ts/#L42)

</details>

<span id="api-PlotSeriesProps-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/plot-types.ts:44](/source/packages/core/src/features/viz/lib/plot-types-ts/#L44)

</details>

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

##### 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/plot-types.ts:53](/source/packages/core/src/features/viz/lib/plot-types-ts/#L53)

</details>

<span id="api-PlotSeriesProps-keyBy"></span>
<details>
<summary>keyBy (optional)</summary>


```ts
readonly keyBy?: PlotKeyAccessor<D> | undefined
```

Related API: [PlotKeyAccessor](/reference/components/plot-series/).

Property or callback supplying stable identity for each datum. See PlotKeyAccessor.

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

</details>

<span id="api-PlotSeriesProps-render"></span>
<details>
<summary>render</summary>


```ts
readonly render: (datum: D, index: number, data: readonly D[]) => PibblNode
```

Related API: [PibblNode](/reference/types/elements-components/#pibblnode).

Renders the current data or resources using the supplied context. See PibblNode.

##### Parameters

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

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

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

##### Returns

Pibbl content to place at the datum's mapped coordinates. See [PibblNode](/reference/types/elements-components/#pibblnode).

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

</details>

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

### PlotKeyAccessor

A property or callback that provides stable identity for a plotted datum.

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

Related API: [PlotKeyAccessor](/reference/components/plot-series/).

#### Parameters

- **`datum`** — Datum requiring an identity.

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

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

#### Returns

A stable string or numeric key for the datum.

#### See also

[PlotSeriesProps](/reference/components/plot-series/)

[PieOptions](/reference/functions/pie-slices/)

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

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

- [Point and custom plot series](/minimal-examples/viz/points/): Render styled point marks and custom keyed point content. [Plain source](/minimal/viz/points.tsx)
## Documentation version

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