# Grid and reference lines

Import `GridLines` and `ReferenceLine` from `@pibbl/core/viz`.
`GridLines(props: GridLinesProps)` and `ReferenceLine(props: ReferenceLineProps)`
return ordinary decorative Pibbl lines. They allocate no layout, labels, titles,
or interaction regions. Source order controls painting; place them before marks.

Both require `scale: ScaleId`, `direction: "horizontal" | "vertical"`, and
`span: SignalValue<readonly [number, number]>`. Direction is the direction the
line extends: horizontal lines map values to y, vertical lines map values to x.
The span supplies the other coordinate's two endpoints in local logical pixels.
Descending and zero-length spans are valid. Nothing is implicitly clipped.

`GridLines` accepts either `tickValues: SignalValue<readonly (number | string)[]>`
or `tickCount?: SignalValue<number>` (default 5), never both. It uses exactly the
Axis tick selection rules, including band centers and point positions. Explicit
ticks must be unique, in-domain values, at most 100. Count is an integer 0–100;
zero paints nothing. Scale ticks may interpret positive count as a target.
Grid density is independent of label visibility; share explicit tick values with
an Axis when their positions must match.

`ReferenceLine` requires `value: SignalValue<string | number>`. Continuous scales
require a finite numeric in-domain value; categorical scales require a known
category. Band references pass through band centers.

Both accept a signal-valued `style` with signal-valued `stroke` (default
`#dce5e8`), `strokeWidth` (default 1), and `opacity` (default 1). Width must be
finite and nonnegative; opacity must be finite and between 0 and 1. Lines ignore
pointer events. Wrap them in ordinary core compositions for transforms/clipping.

Missing/unknown scale IDs and invalid directions throw `TypeError`. Invalid
spans, out-of-domain/duplicate ticks, invalid counts, widths, or opacity throw
`RangeError`; nonnumeric continuous values throw `TypeError`. Scale-provider
validation still applies. Signal changes schedule geometry/paint updates;
subscription ownership ends on removal or disposal.

## Minimal runnable composition

```tsx
import { pibbl } from "@pibbl/core";
import { LinearScale, GridLines, ReferenceLine } from "@pibbl/core/viz";
export default function mount(canvas: HTMLCanvasElement) {
  return pibbl(
    canvas,
    <LinearScale id="y" domain={[-10, 10]} range={[180, 20]}>
      <GridLines
        scale="y"
        direction="horizontal"
        span={[20, 280]}
        tickValues={[-10, 0, 10]}
      />
      <ReferenceLine
        scale="y"
        direction="horizontal"
        span={[20, 280]}
        value={0}
        style={{ stroke: "#087f8c", strokeWidth: 2 }}
      />
    </LinearScale>,
  );
}
```

The [signed population example](/playground/#/examples/composition/viz-signed-population)
uses horizontal guides and a zero reference across responsive symlog geometry.

## Reference bands

`ReferenceBand(props: ReferenceBandProps)` paints a continuous numeric interval.
It takes the same required `scale`, `direction`, and signal-valued pixel `span`
as lines, plus `values: SignalValue<readonly [number, number]>`. Endpoints may
be ascending, descending, or equal. Reversed ranges work normally. Equal values
or a zero-length span paint zero area. The interval must stay within the domain;
there is no implicit clipping or extrapolation. Linear, UTC, log, and symlog
scales are supported. UTC values are epoch milliseconds.

Its signal-valued `style` accepts signal-valued `fill` (default `#dce5e8`) and
`opacity` (default 0.35). It paints no border, labels, or hit target. Place it
before grid lines and marks; the parent owns allocation and source order.
Signals update geometry and paint, and subscriptions detach on removal/disposal.
Missing/unknown scale IDs, categorical scales, and invalid directions throw
`TypeError`; malformed/nonfinite endpoint pairs, out-of-domain values, overflowing
span length, and invalid opacity throw `RangeError`.

Minimal runnable band demo:

```tsx
import { pibbl } from "@pibbl/core";
import { LinearScale, ReferenceBand } from "@pibbl/core/viz";
export default function mount(canvas: HTMLCanvasElement) {
  return pibbl(
    canvas,
    <LinearScale id="y" domain={[-10, 10]} range={[180, 20]}>
      <ReferenceBand
        scale="y"
        direction="horizontal"
        span={[20, 280]}
        values={[-10, 0]}
        style={{ fill: "#b65a35", opacity: 0.1 }}
      />
    </LinearScale>,
  );
}
```

The population example shades the negative half of its domain to distinguish
population loss from gain; this is a sign region, not a confidence interval.

## API details from source

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

### GridLines

Paint grid lines at scale ticks, without labels or allocation.

```ts
GridLines: (props: GridLinesProps) => JSX.Element[]
```

Related API: [GridLines](/reference/components/chart-lines/), [GridLinesProps](/reference/components/chart-lines/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Scale geometry and presentation. See [GridLinesProps](/reference/components/chart-lines/).

#### Returns

Decorative chart content in the caller's coordinate space.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:58](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L58)

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

### ReferenceLine

Paint one decorative line at a domain value, without labels or allocation.

```ts
ReferenceLine: (props: ReferenceLineProps) => JSX.Element[]
```

Related API: [ReferenceLine](/reference/components/chart-lines/), [ReferenceLineProps](/reference/components/chart-lines/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Scale geometry and presentation. See [ReferenceLineProps](/reference/components/chart-lines/).

#### Returns

Decorative chart content in the caller's coordinate space.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:63](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L63)

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

### ChartLineProps

Shared geometry and paint for decorative chart lines; no layout is allocated. See GridLines.

```ts
interface ChartLineProps
```

Related API: [ChartLineProps](/reference/components/chart-lines/).

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:8](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L8)

#### Properties and methods

<span id="api-ChartLineProps-scale"></span>
<details>
<summary>scale</summary>


```ts
readonly scale: ScaleId
```

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

Ancestor scale providing the line's mapped coordinate.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:10](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L10)

</details>

<span id="api-ChartLineProps-direction"></span>
<details>
<summary>direction</summary>


```ts
readonly direction: "horizontal" | "vertical"
```

Direction the painted line extends.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:12](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L12)

</details>

<span id="api-ChartLineProps-span"></span>
<details>
<summary>span</summary>


```ts
readonly span: SignalValue<readonly [number, number]>
```

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

Explicit perpendicular pixel endpoints, in the caller's local coordinate space.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:14](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L14)

</details>

<span id="api-ChartLineProps-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>; }>> | undefined
```

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

Stroke defaults to #dce5e8, width to 1, opacity to 1.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:16](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L16)

</details>

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

### GridLinesProps

Grid positions use Axis tick rules, independent of Axis label visibility. See GridLines.

```ts
type GridLinesProps = ChartLineProps & (
  {
    /** Explicit domain ticks; same validation as Axis. */
    readonly tickValues: AxisProps["tickValues"];
    /** Mutually exclusive with explicit values. */
    readonly tickCount?: never;
  } |
  {
    /** Mutually exclusive with generated ticks. */
    readonly tickValues?: never;
    /** Requested tick count; defaults to five. */
    readonly tickCount?: AxisProps["tickCount"];
  }
)
```

Related API: [GridLinesProps](/reference/components/chart-lines/), [ChartLineProps](/reference/components/chart-lines/), [Axis](/reference/components/axis/), [AxisProps](/reference/components/axis/).

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:19](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L19)

#### Properties and methods

<span id="api-GridLinesProps-scale"></span>
<details>
<summary>scale</summary>


```ts
readonly scale: ScaleId
```

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

Ancestor scale providing the line's mapped coordinate.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:10](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L10)

</details>

<span id="api-GridLinesProps-direction"></span>
<details>
<summary>direction</summary>


```ts
readonly direction: "horizontal" | "vertical"
```

Direction the painted line extends.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:12](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L12)

</details>

<span id="api-GridLinesProps-span"></span>
<details>
<summary>span</summary>


```ts
readonly span: SignalValue<readonly [number, number]>
```

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

Explicit perpendicular pixel endpoints, in the caller's local coordinate space.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:14](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L14)

</details>

<span id="api-GridLinesProps-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>; }>> | undefined
```

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

Stroke defaults to #dce5e8, width to 1, opacity to 1.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:16](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L16)

</details>

<span id="api-GridLinesProps-tickValues"></span>
<details>
<summary>tickValues (optional)</summary>


```ts
readonly tickValues?: SignalValue<readonly (string | number)[]> | undefined
```

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

Explicit domain ticks; same validation as Axis.
Mutually exclusive with generated ticks.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:22](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L22)

</details>

<span id="api-GridLinesProps-tickCount"></span>
<details>
<summary>tickCount (optional)</summary>


```ts
readonly tickCount?: SignalValue<number> | undefined
```

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

Mutually exclusive with explicit values.
Requested tick count; defaults to five.

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

</details>

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

### ReferenceLineProps

A reference value must belong to the selected scale's domain. See ReferenceLine.

```ts
interface ReferenceLineProps extends ChartLineProps
```

Related API: [ReferenceLineProps](/reference/components/chart-lines/), [ChartLineProps](/reference/components/chart-lines/).

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:34](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L34)

#### Properties and methods

<span id="api-ReferenceLineProps-value"></span>
<details>
<summary>value</summary>


```ts
readonly value: SignalValue<BandCategory>
```

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

Numeric domain value or categorical identity; signals update the line.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:36](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L36)

</details>

<span id="api-ReferenceLineProps-scale"></span>
<details>
<summary>scale</summary>


```ts
readonly scale: ScaleId
```

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

Ancestor scale providing the line's mapped coordinate.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:10](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L10)

</details>

<span id="api-ReferenceLineProps-direction"></span>
<details>
<summary>direction</summary>


```ts
readonly direction: "horizontal" | "vertical"
```

Direction the painted line extends.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:12](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L12)

</details>

<span id="api-ReferenceLineProps-span"></span>
<details>
<summary>span</summary>


```ts
readonly span: SignalValue<readonly [number, number]>
```

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

Explicit perpendicular pixel endpoints, in the caller's local coordinate space.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:14](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L14)

</details>

<span id="api-ReferenceLineProps-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>; }>> | undefined
```

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

Stroke defaults to #dce5e8, width to 1, opacity to 1.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:16](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L16)

</details>

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

### ReferenceBand

Paint a decorative interval without owning layout, labels, or hit geometry.

```ts
ReferenceBand: (props: ReferenceBandProps) => JSX.Element
```

Related API: [ReferenceBand](/reference/components/chart-lines/), [ReferenceBandProps](/reference/components/chart-lines/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Scale geometry and presentation. See [ReferenceBandProps](/reference/components/chart-lines/).

#### Returns

Decorative chart content in the caller's coordinate space.

[View source — packages/core/src/features/viz/lib/reference-band.tsx:18](/source/packages/core/src/features/viz/lib/reference-band-tsx/#L18)

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

### ReferenceBandProps

A continuous domain interval painted across an explicit local pixel span. See ReferenceBand.

```ts
interface ReferenceBandProps extends Omit<ChartLineProps, "style">
```

Related API: [ReferenceBandProps](/reference/components/chart-lines/), [ChartLineProps](/reference/components/chart-lines/).

[View source — packages/core/src/features/viz/lib/reference-band.tsx:8](/source/packages/core/src/features/viz/lib/reference-band-tsx/#L8)

#### Properties and methods

<span id="api-ReferenceBandProps-values"></span>
<details>
<summary>values</summary>


```ts
readonly values: SignalValue<readonly [number, number]>
```

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

Two finite in-domain numeric endpoints; either order, including equal values.

[View source — packages/core/src/features/viz/lib/reference-band.tsx:10](/source/packages/core/src/features/viz/lib/reference-band-tsx/#L10)

</details>

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


```ts
readonly style?: SignalValue<Readonly<{ readonly fill?: SignalValue<FillStyle | undefined>; readonly opacity?: SignalValue<number | undefined>; }>> | undefined
```

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

Fill defaults to #dce5e8; opacity defaults to 0.35.

[View source — packages/core/src/features/viz/lib/reference-band.tsx:12](/source/packages/core/src/features/viz/lib/reference-band-tsx/#L12)

</details>

<span id="api-ReferenceBandProps-scale"></span>
<details>
<summary>scale</summary>


```ts
readonly scale: ScaleId
```

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

Ancestor scale providing the line's mapped coordinate.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:10](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L10)

</details>

<span id="api-ReferenceBandProps-direction"></span>
<details>
<summary>direction</summary>


```ts
readonly direction: "horizontal" | "vertical"
```

Direction the painted line extends.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:12](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L12)

</details>

<span id="api-ReferenceBandProps-span"></span>
<details>
<summary>span</summary>


```ts
readonly span: SignalValue<readonly [number, number]>
```

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

Explicit perpendicular pixel endpoints, in the caller's local coordinate space.

[View source — packages/core/src/features/viz/lib/chart-lines.tsx:14](/source/packages/core/src/features/viz/lib/chart-lines-tsx/#L14)

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

- [A target zone and reference line](/minimal-examples/viz/chart-guides/): Compare three tank-fill readings with a shaded target zone, a target line, and percentage grid lines. [Plain source](/minimal/viz/chart-guides.tsx)
## Documentation version

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