# closestPoint

Import from `@pibbl/core/viz`. Creates a function selecting the closest mapped observation across named series.

`data` accepts a readonly array or signal; `x`, `y`, and optional `defined` describe eligibility without invoking renderers. No subscription or scan occurs when constructing a descriptor or query.
`position` is a local point or null (plain or signal), `xScale`/`yScale` name providers, and `series` is a record of descriptors. Optional inclusive `maxDistance` uses local pixels. Ties follow record key then source order. Result includes original datum/index, series key, domain x/y, mapped anchor, and distance. Empty/null inspection returns undefined.

## API details from source

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

### closestPoint

Creates an ordinary query function for the closest mapped recorded point.

```ts
closestPoint: <S extends HoverSeriesMap>(options: ClosestPointOptions<S>) => HoverQuery<ClosestPointHit<S>>
```

Related API: [closestPoint](/reference/functions/closest-point/), [HoverSeriesMap](/reference/functions/define-series/), [ClosestPointOptions](/reference/functions/closest-point/), [HoverQuery](/reference/components/hover-data/), [ClosestPointHit](/reference/functions/closest-point/).

#### Parameters

- **`options`** — Series and distance policy for the hover query. See [ClosestPointOptions](/reference/functions/closest-point/).

#### Returns

A query that selects the closest eligible point, or yields undefined when none
qualifies. See [HoverQuery](/reference/components/hover-data/) , [ClosestPointHit](/reference/functions/closest-point/) .

#### See also

[ClosestPointOptions](/reference/functions/closest-point/)

[HoverQuery](/reference/components/hover-data/)

[ClosestPointHit](/reference/functions/closest-point/)

[HoverSeriesMap](/reference/functions/define-series/)

[View source — packages/core/src/features/viz/lib/hover-queries.ts:43](/source/packages/core/src/features/viz/lib/hover-queries-ts/#L43)

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

### HoverPoint

A logical point used to query or anchor hover presentation.

```ts
interface HoverPoint
```

Related API: [HoverPoint](/reference/functions/closest-point/).

#### See also

[HoverHit](/reference/functions/closest-point/)

[ClosestPointOptions](/reference/functions/closest-point/)

[HoverSample](/reference/functions/interpolate-x/)

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

#### Properties and methods

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


```ts
readonly x: number
```

Horizontal coordinate or displacement in the containing coordinate system. See
HoverPoint.

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

</details>

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


```ts
readonly y: number
```

Vertical coordinate or displacement in the containing coordinate system. See
HoverPoint.

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

</details>

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

### HoverHit

The selected datum, source index, coordinates, and presentation anchor of a hover result.

```ts
interface HoverHit<D>
```

Related API: [HoverHit](/reference/functions/closest-point/).

#### See also

[HoverPoint](/reference/functions/closest-point/)

[ClosestPointHit](/reference/functions/closest-point/)

[ClosestXHit](/reference/functions/closest-x/)

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

#### Properties and methods

<span id="api-HoverHit-datum"></span>
<details>
<summary>datum</summary>


```ts
readonly datum: D
```

The original data item selected by this result. See HoverHit.

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

</details>

<span id="api-HoverHit-index"></span>
<details>
<summary>index</summary>


```ts
readonly index: number
```

Index of the selected datum in its source data. See HoverHit.

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

</details>

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


```ts
readonly x: number
```

Horizontal coordinate or displacement in the containing coordinate system. See
HoverHit.

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

</details>

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


```ts
readonly y: number
```

Vertical coordinate or displacement in the containing coordinate system. See HoverHit
.

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

</details>

<span id="api-HoverHit-anchor"></span>
<details>
<summary>anchor</summary>


```ts
readonly anchor: HoverPoint
```

Related API: [HoverPoint](/reference/functions/closest-point/).

Logical point to which the content or result is anchored. See HoverPoint.

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

</details>

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

### ClosestPointHit

A closest-point result retaining the selected series identity and distance.

```ts
type ClosestPointHit<S extends HoverSeriesMap> = {
  [K in keyof S & string]: S[K] extends HoverSeries<infer D>
    ? HoverHit<D> & {
        /**
         * The named series or series collection participating in the query. See
         * {@link ClosestPointHit}.
         */
        readonly series: K;
        /** Distance measured in this query or guide's coordinate system. See {@link ClosestPointHit}. */
        readonly distance: number;
      }
    : never;
}[keyof S & string]
```

Related API: [ClosestPointHit](/reference/functions/closest-point/), [HoverSeriesMap](/reference/functions/define-series/), [HoverSeries](/reference/functions/define-series/), [HoverHit](/reference/functions/closest-point/).

#### See also

[HoverSeriesMap](/reference/functions/define-series/)

[HoverSeries](/reference/functions/define-series/)

[HoverHit](/reference/functions/closest-point/)

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

#### Properties and methods

<span id="api-ClosestPointHit-datum"></span>
<details>
<summary>datum</summary>


```ts
readonly datum: unknown
```

The original data item selected by this result. See HoverHit.

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

</details>

<span id="api-ClosestPointHit-index"></span>
<details>
<summary>index</summary>


```ts
readonly index: number
```

Index of the selected datum in its source data. See HoverHit.

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

</details>

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


```ts
readonly x: number
```

Horizontal coordinate or displacement in the containing coordinate system. See
HoverHit.

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

</details>

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


```ts
readonly y: number
```

Vertical coordinate or displacement in the containing coordinate system. See HoverHit
.

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

</details>

<span id="api-ClosestPointHit-anchor"></span>
<details>
<summary>anchor</summary>


```ts
readonly anchor: HoverPoint
```

Related API: [HoverPoint](/reference/functions/closest-point/).

Logical point to which the content or result is anchored. See HoverPoint.

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

</details>

<span id="api-ClosestPointHit-series"></span>
<details>
<summary>series</summary>


```ts
readonly series: keyof S & string
```

The named series or series collection participating in the query. See
ClosestPointHit.

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

</details>

<span id="api-ClosestPointHit-distance"></span>
<details>
<summary>distance</summary>


```ts
readonly distance: number
```

Distance measured in this query or guide's coordinate system. See ClosestPointHit.

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

</details>

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

### ClosestPointOptions

Series, query point, scales, and distance limit for closest-point hover selection.

```ts
interface ClosestPointOptions<S extends HoverSeriesMap>
```

Related API: [ClosestPointOptions](/reference/functions/closest-point/), [HoverSeriesMap](/reference/functions/define-series/).

#### See also

[HoverSeriesMap](/reference/functions/define-series/)

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

[HoverPoint](/reference/functions/closest-point/)

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

[closestPoint](/reference/functions/closest-point/)

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

#### Properties and methods

<span id="api-ClosestPointOptions-series"></span>
<details>
<summary>series</summary>


```ts
readonly series: S
```

The named series or series collection participating in the query. See
ClosestPointOptions.

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

</details>

<span id="api-ClosestPointOptions-position"></span>
<details>
<summary>position</summary>


```ts
readonly position: SignalValue<HoverPoint | null>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue), [HoverPoint](/reference/functions/closest-point/).

Position of the geometry, source, or selected resize handle. See SignalValue,
HoverPoint.

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

</details>

<span id="api-ClosestPointOptions-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/hover-types.ts:173](/source/packages/core/src/features/viz/lib/hover-types-ts/#L173)

</details>

<span id="api-ClosestPointOptions-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/hover-types.ts:175](/source/packages/core/src/features/viz/lib/hover-types-ts/#L175)

</details>

<span id="api-ClosestPointOptions-maxDistance"></span>
<details>
<summary>maxDistance (optional)</summary>


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

Maximum distance accepted by the query. See ClosestPointOptions.

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

</details>

## Implementation guidance for agents

Read the [Authoring, signals, and lifecycle companion](/agents/topics/lifecycle/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Hover query helpers](/minimal-examples/viz/hover-queries/): Run closest-point, closest-x, and interpolated-x queries against a scale context. [Plain source](/minimal/viz/hover-queries.ts)
## Documentation version

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