# Trajectory series

`TrajectorySeries` draws separate participant paths from interleaved long-form
records. `group` is a string/number field or synchronous accessor. Each group's
source order is preserved; the component never sorts visits or calculates a
summary. Supply rows for missed scheduled visits with null coordinates so the
path breaks. An absent row cannot communicate that a scheduled visit was missed.

```tsx
import { TrajectorySeries } from "@pibbl/core/viz";
const visits = [
  { participant: "P01", week: 0, change: 0 },
  { participant: "P01", week: 4, change: null },
  { participant: "P01", week: 12, change: -18 },
];
<TrajectorySeries
  data={visits}
  group="participant"
  x="week"
  y="change"
  xScale="week"
  yScale="change"
  style={{ stroke: "#087f8c" }}
/>;
```

Required props are `data`, `group`, `x`, `y`, `xScale`, and `yScale`.
X coordinates use continuous numeric or categorical PointScale positions; y outcomes use numeric scales. Missing
or nonfinite coordinates split only their group's current run; one-point runs
have no connecting segment. Nullish group keys omit a row. Other group keys must
be strings or finite numbers. `defined=false` breaks the identified group's run
before coordinate accessors are evaluated.

Shared `style` supports `stroke` (default `#2563eb`), `strokeWidth` (default
2 local units), `opacity` (default 1), `cursor`, and `lineInteractionWidth`
(default stroke width). Whole-object and shallow field signals schedule updates.
Each component returns one batched ordinary Pibbl Path, with standard events and
`pointerEvents`. Events do not infer a participant or datum. Accessors are
synchronous and cannot call hooks or write signals. The component owns no
retained resources or statistical state.

## API details from source

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

### TrajectorySeries

Draws one shared-style path connecting each participant or specimen trajectory.

A missing, excluded, or non-finite coordinate ends only that group's current
run. Interleaved groups retain their source encounter order; trajectories are
never sorted by either actual or scheduled time.

```ts
TrajectorySeries: <D>({ data: input, group: groupInput, x: xInput, y: yInput, xScale: xId, yScale: yId, defined, style: styleInput, ...events }: TrajectorySeriesProps<D>) => JSX.Element
```

Related API: [TrajectorySeries](/reference/components/trajectory-series/), [TrajectorySeriesProps](/reference/components/trajectory-series/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Observations, identities, coordinates, scales, and shared path paint.

#### Returns

One batched ordinary Pibbl path containing source-ordered trajectory segments.

#### See also

[TrajectorySeriesProps](/reference/components/trajectory-series/)

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:148](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L148)

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

### TrajectorySeriesProps

Authoring inputs for TrajectorySeries.

Rows are connected in source encounter order within each group. The component
neither sorts time values nor invents visits, summaries, or missing values.

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

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

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

#### Properties and methods

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


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

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

Source observations or a signal containing them.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:65](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L65)

</details>

<span id="api-TrajectorySeriesProps-group"></span>
<details>
<summary>group</summary>


```ts
readonly group: TrajectoryGroupAccessor<D>
```

Related API: [TrajectoryGroupAccessor](/reference/components/trajectory-series/).

Stable participant or specimen identity. Nullish identities omit that row.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:67](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L67)

</details>

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


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

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

Encounter-time or scheduled-visit coordinate.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:69](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L69)

</details>

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


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

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

Numeric observed outcome coordinate.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:71](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L71)

</details>

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


```ts
readonly xScale: ScaleId
```

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

Scale mapping encounter-time or visit coordinates.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:73](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L73)

</details>

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


```ts
readonly yScale: ScaleId
```

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

Numeric scale mapping outcomes.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:75](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L75)

</details>

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


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

Ends that group's current run without reading coordinate accessors.

##### Parameters

- **`datum`** — Candidate source datum.

- **`index`** — Zero-based source index.

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

##### Returns

Whether this datum contributes a coordinate to its group.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:83](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L83)

</details>

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


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

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

Shared path style, including whole-object and shallow field signals.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:85](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L85)

</details>

<span id="api-TrajectorySeriesProps-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-TrajectorySeriesStyle"></span>

### TrajectorySeriesStyle

Shared path appearance for TrajectorySeries.

```ts
interface TrajectorySeriesStyle
```

Related API: [TrajectorySeriesStyle](/reference/components/trajectory-series/).

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:21](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L21)

#### Properties and methods

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


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

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

Path paint. Defaults to `#2563eb`.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:23](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L23)

</details>

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


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

Visible path width in local units. Defaults to 2.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:25](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L25)

</details>

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


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

Pointer targeting width. Defaults to `strokeWidth`.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:27](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L27)

</details>

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


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

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

Path opacity in [0, 1]. Defaults to 1.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:29](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L29)

</details>

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


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

Cursor while the batched path owns pointer presentation.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:31](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L31)

</details>

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

### TrajectoryGroupAccessor

A participant or specimen identity property or callback.

Nullish identities deliberately omit a row. Numeric identities must be finite.

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

Related API: [TrajectoryGroupAccessor](/reference/components/trajectory-series/).

#### Parameters

- **`datum`** — Source observation.

- **`index`** — Zero-based source index.

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

#### Returns

A finite numeric or string identity, or a nullish omitted identity.

#### See also

[TrajectorySeriesProps](/reference/components/trajectory-series/)

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

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

- [Participant trajectories with explicit missing visits](/minimal-examples/viz/trajectory-series/): Participant trajectories with explicit missing visits. [Plain source](/minimal/viz/trajectory-series.tsx)
## Documentation version

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