insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/index.d.ts

@@ -0,0 +1,20 @@
+export { point, type PointChannels, type PointOptions } from "./point.ts";
+export { line, type LineChannels, type LineOptions } from "./line.ts";
+export { connectedScatter, type ConnectedScatterChannels, type ConnectedScatterOptions, } from "./connected-scatter.ts";
+export { area, type AreaChannels, type AreaOptions, type AreaPosition } from "./area.ts";
+export { bar, type BarChannels, type BarOptions, type BarPosition } from "./bar.ts";
+export { histogram, type HistogramChannels, type HistogramMeasure, type HistogramOptions, type HistogramPosition, } from "./histogram.ts";
+export { rug, type RugChannels, type RugOptions, type RugSide } from "./rug.ts";
+export { rule, type RuleChannels, type RuleOptions } from "./rule.ts";
+export { smooth, type SmoothChannels, type SmoothLabelOptions, type SmoothMethod, type SmoothOptions, } from "./smooth.ts";
+export { statRolling, type StatRollingChannels, type StatRollingOptions } from "./rolling.ts";
+export { ribbon, type RibbonChannels, type RibbonOptions } from "./ribbon.ts";
+export { interval, type IntervalChannels, type IntervalOptions } from "./interval.ts";
+export { band, type BandChannels, type BandOptions } from "./band.ts";
+export { text, type TextChannels, type TextOptions } from "./text.ts";
+export { boxplot, type BoxplotChannels, type BoxplotOptions, type PointsMode } from "./boxplot.ts";
+export { violin, type ViolinChannels, type ViolinInner, type ViolinOptions, type ViolinScale, } from "./violin.ts";
+export { ridgeline, type RidgelineChannels, type RidgelineFillMode, type RidgelineGeom, type RidgelineInner, type RidgelineOptions, type RidgelineScale, } from "./ridgeline.ts";
+export { tile, type TileChannels, type TileNAOptions, type TileOptions } from "./tile.ts";
+export { aggregate, type AggregateBinBy, type AggregateBinSize, type AggregateBinView, type AggregateBundleResult, type AggregateBundleSummary, type AggregateBundleSummaryKind, type AggregateChannels, type AggregateInnerGeom, type AggregateOptions, type AggregateSummary, type AggregateSummaryKind, type AutoBinSizeInfo, } from "./aggregate.ts";
+export type { ChannelSpec, CompileContext, CompiledHitTest, Geom, GeomKind, HoveredHit, PositionScaleHint, PrepareRangeContext, RangeHints, ResolvedChannelMap, ScaleBundle, ScaleHints, } from "./types.ts";

package/src/grammar/geoms/index.ts

@@ -0,0 +1,77 @@
+export { point, type PointChannels, type PointOptions } from "./point.ts";
+export { line, type LineChannels, type LineOptions } from "./line.ts";
+export {
+  connectedScatter,
+  type ConnectedScatterChannels,
+  type ConnectedScatterOptions,
+} from "./connected-scatter.ts";
+export { area, type AreaChannels, type AreaOptions, type AreaPosition } from "./area.ts";
+export { bar, type BarChannels, type BarOptions, type BarPosition } from "./bar.ts";
+export {
+  histogram,
+  type HistogramChannels,
+  type HistogramMeasure,
+  type HistogramOptions,
+  type HistogramPosition,
+} from "./histogram.ts";
+export { rug, type RugChannels, type RugOptions, type RugSide } from "./rug.ts";
+export { rule, type RuleChannels, type RuleOptions } from "./rule.ts";
+export {
+  smooth,
+  type SmoothChannels,
+  type SmoothLabelOptions,
+  type SmoothMethod,
+  type SmoothOptions,
+} from "./smooth.ts";
+export { statRolling, type StatRollingChannels, type StatRollingOptions } from "./rolling.ts";
+export { ribbon, type RibbonChannels, type RibbonOptions } from "./ribbon.ts";
+export { interval, type IntervalChannels, type IntervalOptions } from "./interval.ts";
+export { band, type BandChannels, type BandOptions } from "./band.ts";
+export { text, type TextChannels, type TextOptions } from "./text.ts";
+export { boxplot, type BoxplotChannels, type BoxplotOptions, type PointsMode } from "./boxplot.ts";
+export {
+  violin,
+  type ViolinChannels,
+  type ViolinInner,
+  type ViolinOptions,
+  type ViolinScale,
+} from "./violin.ts";
+export {
+  ridgeline,
+  type RidgelineChannels,
+  type RidgelineFillMode,
+  type RidgelineGeom,
+  type RidgelineInner,
+  type RidgelineOptions,
+  type RidgelineScale,
+} from "./ridgeline.ts";
+export { tile, type TileChannels, type TileNAOptions, type TileOptions } from "./tile.ts";
+export {
+  aggregate,
+  type AggregateBinBy,
+  type AggregateBinSize,
+  type AggregateBinView,
+  type AggregateBundleResult,
+  type AggregateBundleSummary,
+  type AggregateBundleSummaryKind,
+  type AggregateChannels,
+  type AggregateInnerGeom,
+  type AggregateOptions,
+  type AggregateSummary,
+  type AggregateSummaryKind,
+  type AutoBinSizeInfo,
+} from "./aggregate.ts";
+export type {
+  ChannelSpec,
+  CompileContext,
+  CompiledHitTest,
+  Geom,
+  GeomKind,
+  HoveredHit,
+  PositionScaleHint,
+  PrepareRangeContext,
+  RangeHints,
+  ResolvedChannelMap,
+  ScaleBundle,
+  ScaleHints,
+} from "./types.ts";

package/src/grammar/geoms/interval.d.ts

@@ -0,0 +1,31 @@
+import type { Aes } from "../aes.ts";
+import { type ColorOrAccent } from "../color-utils.ts";
+import type { Geom } from "./types.ts";
+export interface IntervalChannels<T> {
+    /** Anchor for vertical intervals (required when `yMin`/`yMax` are bound). */
+    x?: Aes<T, number | Date>;
+    /** Anchor for horizontal intervals (required when `xMin`/`xMax` are bound). */
+    y?: Aes<T, number | Date>;
+    yMin?: Aes<T, number | Date>;
+    yMax?: Aes<T, number | Date>;
+    xMin?: Aes<T, number | Date>;
+    xMax?: Aes<T, number | Date>;
+    /** Optional categorical color channel — routed through the chart's color scale. */
+    color?: Aes<T, unknown>;
+}
+export interface IntervalOptions {
+    /**
+     * Stroke color. Accepts a literal {@link Color} or a theme accent key
+     * (`"positive" | "negative" | "warn" | "info"`); accent keys resolve through
+     * `theme.accents`.
+     */
+    stroke?: ColorOrAccent;
+    strokeWidth?: number;
+    /** Render perpendicular caps at each end. Default `true`. */
+    caps?: boolean;
+    /** Cap length in pixels (total, across both sides of the spine). Default `6`. */
+    capWidth?: number;
+    /** Display label for legend. */
+    label?: string;
+}
+export declare function interval<T>(channels: IntervalChannels<T>, options?: IntervalOptions): Geom<T>;

package/src/grammar/geoms/interval.test.ts

@@ -0,0 +1,154 @@
+// @vitest-environment jsdom
+import { createFrame } from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+
+import { resolveAes } from "../aes.ts";
+import { plot } from "../chart.ts";
+import { buildPositionScale, type ScaleBundle } from "../scales.ts";
+import { themeDefault } from "../theme.ts";
+import { interval } from "./interval.ts";
+import type { CompileContext } from "./types.ts";
+
+interface Row {
+  t: number;
+  lo: number;
+  hi: number;
+  group?: string;
+}
+
+const rows: Row[] = [
+  { t: 0, lo: 1, hi: 3 },
+  { t: 1, lo: 2, hi: 5 },
+  { t: 2, lo: 0, hi: 4 },
+];
+
+function makeCtx(data: readonly Row[]): CompileContext<Row> {
+  const xAes = resolveAes<Row, unknown>("t");
+  const yAes = resolveAes<Row, unknown>("hi");
+  // Pin domains so pixel math is predictable in tests.
+  const xScale = buildPositionScale(xAes, data, [0, 100], {
+    type: "linear",
+    domain: [0, 2],
+  });
+  const yScale = buildPositionScale(yAes, data, [200, 0], {
+    type: "linear",
+    domain: [0, 5],
+  });
+  const scales: ScaleBundle = { x: xScale, y: yScale };
+  return {
+    data,
+    scales,
+    plot: createFrame({ x: 50, y: 30, width: 100, height: 200 }),
+    theme: themeDefault,
+    atlas: undefined,
+  };
+}
+
+describe("interval geom — direction inference", () => {
+  test("throws when neither (yMin,yMax) nor (xMin,xMax) is provided", () => {
+    expect(() => interval<Row>({ x: "t" })).toThrow(/yMin.*yMax.*xMin.*xMax/);
+  });
+
+  test("throws when both pairs are provided", () => {
+    expect(() =>
+      interval<Row>({ x: "t", y: "t", yMin: "lo", yMax: "hi", xMin: "lo", xMax: "hi" }),
+    ).toThrow(/not both/);
+  });
+
+  test("throws when vertical pair lacks x anchor", () => {
+    expect(() => interval<Row>({ yMin: "lo", yMax: "hi" })).toThrow(/`x` is required/);
+  });
+
+  test("throws when horizontal pair lacks y anchor", () => {
+    expect(() => interval<Row>({ xMin: "lo", xMax: "hi" })).toThrow(/`y` is required/);
+  });
+});
+
+describe("interval geom — prepareDomain", () => {
+  test("vertical: extends y scale to union of yMin and yMax", () => {
+    const geom = interval<Row>({ x: "t", yMin: "lo", yMax: "hi" });
+    const hints = geom.prepareDomain!(rows);
+    expect(hints?.y?.extend).toEqual([0, 5]);
+  });
+
+  test("horizontal: extends x scale to union of xMin and xMax", () => {
+    const geom = interval<Row>({ y: "t", xMin: "lo", xMax: "hi" });
+    const hints = geom.prepareDomain!(rows);
+    expect(hints?.x?.extend).toEqual([0, 5]);
+  });
+
+  test("returns undefined when there is no finite data", () => {
+    const geom = interval<Row>({ x: "t", yMin: "lo", yMax: "hi" });
+    expect(geom.prepareDomain!([])).toBeUndefined();
+  });
+});
+
+describe("interval geom — compileHitTest", () => {
+  test("vertical: one hit per row at (x, midY) with [lo, hi] rect", () => {
+    const geom = interval<Row>({ x: "t", yMin: "lo", yMax: "hi" });
+    const hits = geom.compileHitTest!(makeCtx(rows))!;
+    expect(hits.geomKind).toBe("interval");
+    expect(hits.dataIndex.length).toBe(3);
+    expect(hits.rects).toBeDefined();
+    // x domain [0,2] → range [0,100]: t=0 → 0, plus plot.x(50) = 50.
+    expect(hits.positions[0]).toBeCloseTo(50, 3);
+    // y domain [0,5] → range [200,0]: lo=1 → 160, hi=3 → 80; midY=120, plus plot.y(30) = 150.
+    expect(hits.positions[1]).toBeCloseTo(150, 3);
+    // Rect[0]: x = 50 + 0 - 3 = 47; y = 30 + min(yLo,yHi) = 30 + 80 = 110.
+    expect(hits.rects![0]).toBeCloseTo(47, 3);
+    expect(hits.rects![1]).toBeCloseTo(110, 3);
+  });
+
+  test("horizontal: pos at midX, y anchor; rect spans [xMin, xMax]", () => {
+    const geom = interval<Row>({ y: "t", xMin: "lo", xMax: "hi" });
+    const hits = geom.compileHitTest!(makeCtx(rows))!;
+    expect(hits.geomKind).toBe("interval");
+    expect(hits.dataIndex.length).toBe(3);
+    expect(hits.rects).toBeDefined();
+  });
+
+  test("returns null on empty data", () => {
+    const geom = interval<Row>({ x: "t", yMin: "lo", yMax: "hi" });
+    expect(geom.compileHitTest!(makeCtx([]))).toBeNull();
+  });
+
+  test("skips rows with non-finite values", () => {
+    const partial: Row[] = [
+      { t: 0, lo: 1, hi: 3 },
+      { t: 1, lo: Number.NaN, hi: 5 },
+    ];
+    const geom = interval<Row>({ x: "t", yMin: "lo", yMax: "hi" });
+    const hits = geom.compileHitTest!(makeCtx(partial))!;
+    expect(hits.dataIndex.length).toBe(1);
+    expect(hits.dataIndex[0]).toBe(0);
+  });
+});
+
+describe("interval geom — end to end", () => {
+  // The v3 SVG renderer serializes stroked segments (pushLine/pushSegment) as
+  // <line> elements. Count those to capture the spine + cap segments.
+  function countStrokeLines(svg: SVGSVGElement): number {
+    return svg.querySelectorAll("line").length;
+  }
+
+  test("renders into a plot() and produces stroke segments per row", () => {
+    const svg = plot({ data: rows, width: 320, height: 200 })
+      .layer(interval({ x: "t", yMin: "lo", yMax: "hi" }))
+      .toSVG();
+    expect(svg).toBeInstanceOf(SVGSVGElement);
+    // 1 spine + 2 caps per row × 3 rows = 9 stroke segments.
+    expect(countStrokeLines(svg)).toBe(9);
+  });
+
+  test("caps: false omits cap segments", () => {
+    const svgWithCaps = plot({ data: rows, width: 320, height: 200 })
+      .layer(interval({ x: "t", yMin: "lo", yMax: "hi" }, { caps: true }))
+      .toSVG();
+    const svgNoCaps = plot({ data: rows, width: 320, height: 200 })
+      .layer(interval({ x: "t", yMin: "lo", yMax: "hi" }, { caps: false }))
+      .toSVG();
+    expect(svgWithCaps.querySelectorAll("line").length).toBeGreaterThan(
+      svgNoCaps.querySelectorAll("line").length,
+    );
+  });
+});

package/src/grammar/geoms/interval.ts

@@ -0,0 +1,342 @@
+// ---------------------------------------------------------------------------
+// interval geom — directed [lo, hi] range anchored at a coordinate
+// ---------------------------------------------------------------------------
+// One primitive covers confidence intervals, error bars, candlestick wicks,
+// gantt durations, daily highs/lows, prediction intervals, and IQR whiskers.
+//
+// Direction is inferred from which pair of channels is bound:
+//   - `yMin` + `yMax`  → vertical interval, anchored at `x`
+//   - `xMin` + `xMax`  → horizontal interval, anchored at `y`
+//
+// Pair this with `point()` when a center marker is wanted.
+
+import type { Color, Layer } from "insomni";
+import { lineSwatch } from "../../legend.ts";
+import type { Aes, ResolvedAes } from "../aes.ts";
+import { resolveAes } from "../aes.ts";
+import { alphaize, resolveAccent, type ColorOrAccent } from "../color-utils.ts";
+import type {
+  CompileContext,
+  CompiledHitTest,
+  Geom,
+  ResolvedChannelMap,
+  ScaleHints,
+} from "./types.ts";
+import { selectedIndicesFor, selectionActive, SELECTION_DIM_ALPHA } from "./_mark.ts";
+
+export interface IntervalChannels<T> {
+  /** Anchor for vertical intervals (required when `yMin`/`yMax` are bound). */
+  x?: Aes<T, number | Date>;
+  /** Anchor for horizontal intervals (required when `xMin`/`xMax` are bound). */
+  y?: Aes<T, number | Date>;
+  yMin?: Aes<T, number | Date>;
+  yMax?: Aes<T, number | Date>;
+  xMin?: Aes<T, number | Date>;
+  xMax?: Aes<T, number | Date>;
+  /** Optional categorical color channel — routed through the chart's color scale. */
+  color?: Aes<T, unknown>;
+}
+
+export interface IntervalOptions {
+  /**
+   * Stroke color. Accepts a literal {@link Color} or a theme accent key
+   * (`"positive" | "negative" | "warn" | "info"`); accent keys resolve through
+   * `theme.accents`.
+   */
+  stroke?: ColorOrAccent;
+  strokeWidth?: number;
+  /** Render perpendicular caps at each end. Default `true`. */
+  caps?: boolean;
+  /** Cap length in pixels (total, across both sides of the spine). Default `6`. */
+  capWidth?: number;
+  /** Display label for legend. */
+  label?: string;
+}
+
+type Orientation = "vertical" | "horizontal";
+
+function inferOrientation<T>(channels: IntervalChannels<T>): Orientation {
+  const hasYPair = channels.yMin !== undefined && channels.yMax !== undefined;
+  const hasXPair = channels.xMin !== undefined && channels.xMax !== undefined;
+  if (hasYPair && hasXPair) {
+    throw new Error(
+      "interval(): bind either (yMin, yMax) or (xMin, xMax) — not both. Direction is inferred from which pair is set.",
+    );
+  }
+  if (hasYPair) {
+    if (channels.x === undefined) {
+      throw new Error("interval(): `x` is required when `yMin`/`yMax` are bound (vertical).");
+    }
+    return "vertical";
+  }
+  if (hasXPair) {
+    if (channels.y === undefined) {
+      throw new Error("interval(): `y` is required when `xMin`/`xMax` are bound (horizontal).");
+    }
+    return "horizontal";
+  }
+  throw new Error(
+    "interval(): one of (yMin, yMax) or (xMin, xMax) must be provided to define the range.",
+  );
+}
+
+function extentOf<T>(
+  aLo: ResolvedAes<T, unknown>,
+  aHi: ResolvedAes<T, unknown>,
+  data: readonly T[],
+): readonly [number, number] | undefined {
+  let lo = Number.POSITIVE_INFINITY;
+  let hi = Number.NEGATIVE_INFINITY;
+  for (let i = 0; i < data.length; i++) {
+    const d = data[i]!;
+    const a = aLo.fn(d, i);
+    const b = aHi.fn(d, i);
+    const an = a instanceof Date ? a.getTime() : (a as number);
+    const bn = b instanceof Date ? b.getTime() : (b as number);
+    if (Number.isFinite(an)) {
+      if (an < lo) lo = an;
+      if (an > hi) hi = an;
+    }
+    if (Number.isFinite(bn)) {
+      if (bn < lo) lo = bn;
+      if (bn > hi) hi = bn;
+    }
+  }
+  return Number.isFinite(lo) && Number.isFinite(hi) ? [lo, hi] : undefined;
+}
+
+export function interval<T>(channels: IntervalChannels<T>, options: IntervalOptions = {}): Geom<T> {
+  const orientation = inferOrientation(channels);
+  const isVertical = orientation === "vertical";
+
+  // Register one end of the range as the "value" channel so the pipeline
+  // picks it up for color/domain inference; prepareDomain extends it with
+  // the other end. (Mirrors `ribbon`'s registration of y1 + extend via y0.)
+  const registeredChannels = isVertical
+    ? { x: channels.x, y: channels.yMax, color: channels.color }
+    : { x: channels.xMax, y: channels.y, color: channels.color };
+
+  return {
+    kind: "interval",
+    channels: registeredChannels,
+    label: options.label,
+    legendSwatch: (color, theme) =>
+      lineSwatch({
+        stroke: color,
+        strokeWidth: options.strokeWidth ?? theme.marks.ruleStrokeWidth,
+      }),
+    prepareDomain(data) {
+      if (isVertical) {
+        const loAes = resolveAes<T, unknown>(channels.yMin as Aes<T, unknown>);
+        const hiAes = resolveAes<T, unknown>(channels.yMax as Aes<T, unknown>);
+        const ext = extentOf(loAes, hiAes, data);
+        if (!ext) return undefined;
+        const hints: ScaleHints = { y: { extend: ext } };
+        return hints;
+      }
+      const loAes = resolveAes<T, unknown>(channels.xMin as Aes<T, unknown>);
+      const hiAes = resolveAes<T, unknown>(channels.xMax as Aes<T, unknown>);
+      const ext = extentOf(loAes, hiAes, data);
+      if (!ext) return undefined;
+      const hints: ScaleHints = { x: { extend: ext } };
+      return hints;
+    },
+    compile(ctx: CompileContext<T>) {
+      const { data, scales, plot, theme } = ctx;
+
+      const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+      const colorScale = scales.color?.fn;
+      const baseStroke: Color =
+        resolveAccent(options.stroke, theme) ?? theme.palettes.categorical(0);
+      const strokeWidth = options.strokeWidth ?? theme.marks.ruleStrokeWidth;
+      const drawCaps = options.caps ?? true;
+      const capHalf = (options.capWidth ?? 6) / 2;
+
+      const hidden = ctx.hidden;
+      const selected = selectedIndicesFor(ctx, "interval");
+      const dimWhenSelected = selectionActive(ctx);
+
+      const ox = plot.topLeft.x;
+      const oy = plot.topLeft.y;
+
+      interface Segment {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+        stroke: Color;
+      }
+      const spines: Segment[] = [];
+      const caps: Segment[] = [];
+
+      if (isVertical) {
+        const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+        const loAes = resolveAes<T, unknown>(channels.yMin as Aes<T, unknown>);
+        const hiAes = resolveAes<T, unknown>(channels.yMax as Aes<T, unknown>);
+        const xFn = scales.x.fn;
+        const yFn = scales.y.fn;
+        for (let i = 0; i < data.length; i++) {
+          const d = data[i]!;
+          if (hidden && colorAes && hidden.has(String(colorAes.fn(d, i)))) continue;
+          const xPx = xFn(xAes.fn(d, i) as never);
+          const yLo = yFn(loAes.fn(d, i) as never);
+          const yHi = yFn(hiAes.fn(d, i) as never);
+          if (!Number.isFinite(xPx) || !Number.isFinite(yLo) || !Number.isFinite(yHi)) continue;
+          let stroke: Color = colorAes && colorScale ? colorScale(colorAes.fn(d, i)) : baseStroke;
+          if (dimWhenSelected && (!selected || !selected.has(i))) {
+            stroke = alphaize(stroke, SELECTION_DIM_ALPHA);
+          }
+          spines.push({ x1: xPx, y1: yLo, x2: xPx, y2: yHi, stroke });
+          if (drawCaps && capHalf > 0) {
+            caps.push({ x1: xPx - capHalf, y1: yLo, x2: xPx + capHalf, y2: yLo, stroke });
+            caps.push({ x1: xPx - capHalf, y1: yHi, x2: xPx + capHalf, y2: yHi, stroke });
+          }
+        }
+      } else {
+        const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+        const loAes = resolveAes<T, unknown>(channels.xMin as Aes<T, unknown>);
+        const hiAes = resolveAes<T, unknown>(channels.xMax as Aes<T, unknown>);
+        const xFn = scales.x.fn;
+        const yFn = scales.y.fn;
+        for (let i = 0; i < data.length; i++) {
+          const d = data[i]!;
+          if (hidden && colorAes && hidden.has(String(colorAes.fn(d, i)))) continue;
+          const yPx = yFn(yAes.fn(d, i) as never);
+          const xLo = xFn(loAes.fn(d, i) as never);
+          const xHi = xFn(hiAes.fn(d, i) as never);
+          if (!Number.isFinite(yPx) || !Number.isFinite(xLo) || !Number.isFinite(xHi)) continue;
+          let stroke: Color = colorAes && colorScale ? colorScale(colorAes.fn(d, i)) : baseStroke;
+          if (dimWhenSelected && (!selected || !selected.has(i))) {
+            stroke = alphaize(stroke, SELECTION_DIM_ALPHA);
+          }
+          spines.push({ x1: xLo, y1: yPx, x2: xHi, y2: yPx, stroke });
+          if (drawCaps && capHalf > 0) {
+            caps.push({ x1: xLo, y1: yPx - capHalf, x2: xLo, y2: yPx + capHalf, stroke });
+            caps.push({ x1: xHi, y1: yPx - capHalf, x2: xHi, y2: yPx + capHalf, stroke });
+          }
+        }
+      }
+
+      const builder = {
+        length: spines.length + caps.length,
+        addTo(layer: Layer): Layer {
+          for (const s of spines) {
+            layer.pushLine({
+              x1: ox + s.x1,
+              y1: oy + s.y1,
+              x2: ox + s.x2,
+              y2: oy + s.y2,
+              color: s.stroke,
+              width: strokeWidth,
+            });
+          }
+          for (const s of caps) {
+            layer.pushLine({
+              x1: ox + s.x1,
+              y1: oy + s.y1,
+              x2: ox + s.x2,
+              y2: oy + s.y2,
+              color: s.stroke,
+              width: strokeWidth,
+            });
+          }
+          return layer;
+        },
+      };
+
+      return [builder];
+    },
+    compileHitTest(ctx: CompileContext<T>): CompiledHitTest<T> | null {
+      const { data, scales, plot } = ctx;
+      const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+      const hidden = ctx.hidden;
+      const capHalf = (options.capWidth ?? 6) / 2;
+      const ox = plot.topLeft.x;
+      const oy = plot.topLeft.y;
+
+      // One hit per row at the spine midpoint; the rect covers [lo, hi] on
+      // the value axis × the cap span on the anchor axis. The hit-layer
+      // prefers rects when present, so the cursor anywhere along the spine
+      // selects the interval.
+      const positions = new Float32Array(data.length * 2);
+      const rects = new Float32Array(data.length * 4);
+      const dataIndex = new Int32Array(data.length);
+      let n = 0;
+
+      const channelsMap: ResolvedChannelMap<T> = isVertical
+        ? {
+            x: resolveAes<T, unknown>(channels.x as Aes<T, unknown>),
+            y: resolveAes<T, unknown>(channels.yMax as Aes<T, unknown>),
+            color: colorAes,
+          }
+        : {
+            x: resolveAes<T, unknown>(channels.xMax as Aes<T, unknown>),
+            y: resolveAes<T, unknown>(channels.y as Aes<T, unknown>),
+            color: colorAes,
+          };
+
+      if (isVertical) {
+        const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+        const loAes = resolveAes<T, unknown>(channels.yMin as Aes<T, unknown>);
+        const hiAes = resolveAes<T, unknown>(channels.yMax as Aes<T, unknown>);
+        const xFn = scales.x.fn;
+        const yFn = scales.y.fn;
+        for (let i = 0; i < data.length; i++) {
+          const d = data[i]!;
+          if (hidden && colorAes && hidden.has(String(colorAes.fn(d, i)))) continue;
+          const xPx = xFn(xAes.fn(d, i) as never);
+          const yLo = yFn(loAes.fn(d, i) as never);
+          const yHi = yFn(hiAes.fn(d, i) as never);
+          if (!Number.isFinite(xPx) || !Number.isFinite(yLo) || !Number.isFinite(yHi)) continue;
+          const yTop = Math.min(yLo, yHi);
+          const yBot = Math.max(yLo, yHi);
+          positions[n * 2] = ox + xPx;
+          positions[n * 2 + 1] = oy + (yTop + yBot) / 2;
+          rects[n * 4] = ox + xPx - capHalf;
+          rects[n * 4 + 1] = oy + yTop;
+          rects[n * 4 + 2] = Math.max(capHalf * 2, 4);
+          rects[n * 4 + 3] = Math.max(yBot - yTop, 1);
+          dataIndex[n] = i;
+          n++;
+        }
+      } else {
+        const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+        const loAes = resolveAes<T, unknown>(channels.xMin as Aes<T, unknown>);
+        const hiAes = resolveAes<T, unknown>(channels.xMax as Aes<T, unknown>);
+        const xFn = scales.x.fn;
+        const yFn = scales.y.fn;
+        for (let i = 0; i < data.length; i++) {
+          const d = data[i]!;
+          if (hidden && colorAes && hidden.has(String(colorAes.fn(d, i)))) continue;
+          const yPx = yFn(yAes.fn(d, i) as never);
+          const xLo = xFn(loAes.fn(d, i) as never);
+          const xHi = xFn(hiAes.fn(d, i) as never);
+          if (!Number.isFinite(yPx) || !Number.isFinite(xLo) || !Number.isFinite(xHi)) continue;
+          const xLeft = Math.min(xLo, xHi);
+          const xRight = Math.max(xLo, xHi);
+          positions[n * 2] = ox + (xLeft + xRight) / 2;
+          positions[n * 2 + 1] = oy + yPx;
+          rects[n * 4] = ox + xLeft;
+          rects[n * 4 + 1] = oy + yPx - capHalf;
+          rects[n * 4 + 2] = Math.max(xRight - xLeft, 1);
+          rects[n * 4 + 3] = Math.max(capHalf * 2, 4);
+          dataIndex[n] = i;
+          n++;
+        }
+      }
+
+      if (n === 0) return null;
+
+      return {
+        geomKind: "interval",
+        label: options.label,
+        positions: positions.subarray(0, n * 2),
+        rects: rects.subarray(0, n * 4),
+        dataIndex: dataIndex.subarray(0, n),
+        pickRadius: Math.max(8, capHalf * 2 + 4),
+        channels: channelsMap,
+        data,
+      };
+    },
+  };
+}

package/src/grammar/geoms/line.d.ts

@@ -0,0 +1,38 @@
+import { type Color } from "insomni";
+import { type LineCurve, type LineDashStyle } from "../../marks.ts";
+import type { Aes } from "../aes.ts";
+import type { Geom } from "./types.ts";
+export interface LineChannels<T> {
+    x: Aes<T, number | Date>;
+    y: Aes<T, number | Date>;
+    /** Categorical color channel splits the line into one stroke per category. */
+    color?: Aes<T, unknown>;
+    /**
+     * Optional ordering aesthetic. When present, rows are connected in ascending
+     * order (globally, or within each color-grouped series).
+     */
+    order?: Aes<T, number | Date>;
+}
+export interface LineOptions {
+    stroke?: Color;
+    strokeWidth?: number;
+    curve?: LineCurve;
+    curveSamples?: number;
+    dashPattern?: readonly number[];
+    /**
+     * Categorical dash treatment. `dashPattern` takes precedence when both
+     * are supplied. See {@link LineDashStyle}.
+     */
+    dashStyle?: LineDashStyle;
+    label?: string;
+    /**
+     * When true, hover hit-tests resolve to the nearest vertex *by x* — the
+     * cursor's vertical position doesn't influence which datum is picked, so
+     * the user can hover anywhere along the line. Default `false` (per-vertex
+     * Euclidean pick within `pickRadius`). For multi-line charts this means
+     * the cursor's x picks one vertex per series; the topmost series wins
+     * via PointCloud zIndex order.
+     */
+    nearestX?: boolean;
+}
+export declare function line<T>(channels: LineChannels<T>, options?: LineOptions): Geom<T>;