Grid and reference lines

Read as Markdown

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

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

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

GridLines

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

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

Related API: GridLines, GridLinesProps, JSX.

Parameters

props — Scale geometry and presentation. See GridLinesProps.

Returns

Decorative chart content in the caller’s coordinate space.

View source — packages/core/src/features/viz/lib/chart-lines.tsx:58

ReferenceLine

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

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

Related API: ReferenceLine, ReferenceLineProps, JSX.

Parameters

props — Scale geometry and presentation. See ReferenceLineProps.

Returns

Decorative chart content in the caller’s coordinate space.

View source — packages/core/src/features/viz/lib/chart-lines.tsx:63

ChartLineProps

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

interface ChartLineProps

Related API: ChartLineProps.

View source — packages/core/src/features/viz/lib/chart-lines.tsx:8

Properties and methods

scale

readonly scale: ScaleId

Related API: ScaleId.

Ancestor scale providing the line’s mapped coordinate.

View source — packages/core/src/features/viz/lib/chart-lines.tsx:10

direction

readonly direction: "horizontal" | "vertical"

Direction the painted line extends.

View source — packages/core/src/features/viz/lib/chart-lines.tsx:12

span

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

Related API: SignalValue.

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

View source — packages/core/src/features/viz/lib/chart-lines.tsx:14

style (optional)

readonly style?: SignalValue<Readonly<{ readonly stroke?: SignalValue<StrokeStyle | undefined>; readonly strokeWidth?: SignalValue<number | undefined>; readonly opacity?: SignalValue<number | undefined>; }>> | undefined

Related API: SignalValue, StrokeStyle, opacity.

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

View source — packages/core/src/features/viz/lib/chart-lines.tsx:16

GridLinesProps

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

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, ChartLineProps, Axis, AxisProps.

View source — packages/core/src/features/viz/lib/chart-lines.tsx:19

Properties and methods

scale

readonly scale: ScaleId

Related API: ScaleId.

Ancestor scale providing the line’s mapped coordinate.

View source — packages/core/src/features/viz/lib/chart-lines.tsx:10

direction

readonly direction: "horizontal" | "vertical"

Direction the painted line extends.

View source — packages/core/src/features/viz/lib/chart-lines.tsx:12

span

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

Related API: SignalValue.

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

View source — packages/core/src/features/viz/lib/chart-lines.tsx:14

style (optional)

readonly style?: SignalValue<Readonly<{ readonly stroke?: SignalValue<StrokeStyle | undefined>; readonly strokeWidth?: SignalValue<number | undefined>; readonly opacity?: SignalValue<number | undefined>; }>> | undefined

Related API: SignalValue, StrokeStyle, opacity.

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

View source — packages/core/src/features/viz/lib/chart-lines.tsx:16

tickValues (optional)

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

Related API: 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

tickCount (optional)

readonly tickCount?: SignalValue<number> | undefined

Related API: SignalValue.

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

View source — packages/core/src/features/viz/lib/chart-lines.tsx:24

ReferenceLineProps

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

interface ReferenceLineProps extends ChartLineProps

Related API: ReferenceLineProps, ChartLineProps.

View source — packages/core/src/features/viz/lib/chart-lines.tsx:34

Properties and methods

value

readonly value: SignalValue<BandCategory>

Related API: SignalValue, BandCategory.

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

View source — packages/core/src/features/viz/lib/chart-lines.tsx:36

scale

readonly scale: ScaleId

Related API: ScaleId.

Ancestor scale providing the line’s mapped coordinate.

View source — packages/core/src/features/viz/lib/chart-lines.tsx:10

direction

readonly direction: "horizontal" | "vertical"

Direction the painted line extends.

View source — packages/core/src/features/viz/lib/chart-lines.tsx:12

span

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

Related API: SignalValue.

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

View source — packages/core/src/features/viz/lib/chart-lines.tsx:14

style (optional)

readonly style?: SignalValue<Readonly<{ readonly stroke?: SignalValue<StrokeStyle | undefined>; readonly strokeWidth?: SignalValue<number | undefined>; readonly opacity?: SignalValue<number | undefined>; }>> | undefined

Related API: SignalValue, StrokeStyle, opacity.

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

View source — packages/core/src/features/viz/lib/chart-lines.tsx:16

ReferenceBand

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

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

Related API: ReferenceBand, ReferenceBandProps, JSX.

Parameters

props — Scale geometry and presentation. See ReferenceBandProps.

Returns

Decorative chart content in the caller’s coordinate space.

View source — packages/core/src/features/viz/lib/reference-band.tsx:18

ReferenceBandProps

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

interface ReferenceBandProps extends Omit<ChartLineProps, "style">

Related API: ReferenceBandProps, ChartLineProps.

View source — packages/core/src/features/viz/lib/reference-band.tsx:8

Properties and methods

values

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

Related API: SignalValue.

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

View source — packages/core/src/features/viz/lib/reference-band.tsx:10

style (optional)

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

Related API: SignalValue, FillStyle, opacity.

Fill defaults to #dce5e8; opacity defaults to 0.35.

View source — packages/core/src/features/viz/lib/reference-band.tsx:12

scale

readonly scale: ScaleId

Related API: ScaleId.

Ancestor scale providing the line’s mapped coordinate.

View source — packages/core/src/features/viz/lib/chart-lines.tsx:10

direction

readonly direction: "horizontal" | "vertical"

Direction the painted line extends.

View source — packages/core/src/features/viz/lib/chart-lines.tsx:12

span

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

Related API: SignalValue.

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

View source — packages/core/src/features/viz/lib/chart-lines.tsx:14

Implementation guidance for agents

Read the Authoring, signals, and lifecycle companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

A target zone and reference line: Compare three tank-fill readings with a shaded target zone, a target line, and percentage grid lines. Plain source

Documentation version

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