insomni-plot 0.1.0-alpha.0

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

@@ -0,0 +1,54 @@
+import type { Color } from "insomni";
+import { type LabelBoxStyle } from "../../annotations.ts";
+import type { Aes } from "../aes.ts";
+import type { Geom } from "./types.ts";
+export type SmoothMethod = "lm" | "poly" | "loess";
+export interface SmoothChannels<T> {
+    x: Aes<T, number | Date>;
+    y: Aes<T, number>;
+    /** Categorical color channel — fits one curve per group. */
+    color?: Aes<T, unknown>;
+}
+export interface SmoothLabelOptions {
+    /** Pixel offset from the right end of the fit. */
+    offsetX?: number;
+    offsetY?: number;
+    /** Custom label color. Defaults to the curve color. */
+    color?: Color;
+    fontSize?: number;
+    /** Optional rounded-rect background. */
+    box?: LabelBoxStyle;
+}
+export interface SmoothOptions {
+    /** Fit method. Default `"lm"`. */
+    method?: SmoothMethod;
+    /** Degree for `"poly"` (default `2`) or `"loess"` local polynomial (default `1`). */
+    degree?: number;
+    /** Span for `"loess"` (fraction of data per neighborhood). Default `0.5`. */
+    span?: number;
+    /**
+     * Confidence ribbon. `true` (default) → 95%, `false` → no ribbon, `number`
+     * → that confidence level (e.g. `0.99`).
+     */
+    ci?: boolean | number;
+    /** Number of x samples for the curve & ribbon. Default `64`. */
+    samples?: number;
+    stroke?: Color;
+    strokeWidth?: number;
+    /** Override the ribbon fill. Defaults to the stroke color at low alpha. */
+    ribbonFill?: Color;
+    ribbonOpacity?: number;
+    /**
+     * Per-group inline label at the right end of each fitted curve. Only emitted
+     * when the `color` channel is present. `true` uses the group key as the
+     * label string.
+     */
+    label?: boolean | SmoothLabelOptions;
+    /**
+     * When true, hit-tests resolve to the nearest sample by x. Hover anywhere
+     * along the curve and the closest source row in the matching group is
+     * picked. Default `false` (Euclidean within `pickRadius`).
+     */
+    nearestX?: boolean;
+}
+export declare function smooth<T>(channels: SmoothChannels<T>, options?: SmoothOptions): Geom<T>;

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

@@ -0,0 +1,78 @@
+import { createFrame } from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+
+import { resolveAes } from "../aes.ts";
+import { buildPositionScale, type ScaleBundle } from "../scales.ts";
+import { themeDefault } from "../theme.ts";
+import { smooth } from "./smooth.ts";
+import type { CompileContext } from "./types.ts";
+
+interface Row {
+  x: number;
+  y: number;
+  series: string;
+}
+
+// Linear data — easy to reason about with method "lm".
+const data: Row[] = [
+  { x: 0, y: 0, series: "a" },
+  { x: 1, y: 2, series: "a" },
+  { x: 2, y: 4, series: "a" },
+  { x: 3, y: 6, series: "a" },
+];
+
+function makeCtx(rows: readonly Row[]): CompileContext<Row> {
+  const xAes = resolveAes<Row, unknown>("x");
+  const yAes = resolveAes<Row, unknown>("y");
+  const xScale = buildPositionScale(xAes, rows, [0, 100]);
+  const yScale = buildPositionScale(yAes, rows, [200, 0]);
+  const scales: ScaleBundle = { x: xScale, y: yScale };
+  return {
+    data: rows,
+    scales,
+    plot: createFrame({ x: 0, y: 0, width: 100, height: 200 }),
+    theme: themeDefault,
+    atlas: undefined,
+  };
+}
+
+describe("smooth geom — compileHitTest", () => {
+  test("emits one hit per source row at the predicted curve y", () => {
+    const geom = smooth<Row>({ x: "x", y: "y" }, { method: "lm", ci: false });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(hits.geomKind).toBe("smooth");
+    expect(hits.dataIndex.length).toBe(4);
+    // Linear fit on (0,0)..(3,6) → y = 2x. Row 0: x=0 → predicted 0.
+    // x=0 maps to range start 0; y=0 maps to range start 200.
+    expect(hits.positions[0]).toBeCloseTo(0, 3);
+    expect(hits.positions[1]).toBeCloseTo(200, 3);
+  });
+
+  test("color channel: emits per-row hits with seriesKey set", () => {
+    const mixed: Row[] = [
+      { x: 0, y: 0, series: "a" },
+      { x: 1, y: 2, series: "a" },
+      { x: 0, y: 1, series: "b" },
+      { x: 1, y: 3, series: "b" },
+    ];
+    const geom = smooth<Row>({ x: "x", y: "y", color: "series" }, { method: "lm", ci: false });
+    const hits = geom.compileHitTest!(makeCtx(mixed))!;
+    expect(hits.dataIndex.length).toBe(4);
+    expect(hits.seriesKey).toBeDefined();
+    const keys = new Set(hits.seriesKey);
+    expect(keys.has("a")).toBe(true);
+    expect(keys.has("b")).toBe(true);
+  });
+
+  test("nearestX option sets pickAxis 'x'", () => {
+    const geom = smooth<Row>({ x: "x", y: "y" }, { method: "lm", ci: false, nearestX: true });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(hits.pickAxis).toBe("x");
+    expect(hits.pickRadius).toBeGreaterThanOrEqual(100);
+  });
+
+  test("returns null for empty data", () => {
+    const geom = smooth<Row>({ x: "x", y: "y" });
+    expect(geom.compileHitTest!(makeCtx([]))).toBeNull();
+  });
+});

package/src/grammar/geoms/smooth.ts

@@ -0,0 +1,337 @@
+// ---------------------------------------------------------------------------
+// smooth geom — fitted regression curve with optional confidence ribbon
+// ---------------------------------------------------------------------------
+// Wraps `linearFit` / `polyFit` / `loessFit` so the chart can render a
+// smoothed reference curve straight from a continuous x/y dataset. Optional
+// 95% (or arbitrary level) confidence ribbon and per-group inline labels
+// when the `color` channel splits the data into series.
+
+import type { Color } from "insomni";
+import { areaMark, lineMark } from "../../marks.ts";
+import { wrapMark } from "./_mark.ts";
+import { valueLabelMark, type LabelBoxStyle } from "../../annotations.ts";
+import {
+  confidenceBand,
+  linearFit,
+  loessFit,
+  polyFit,
+  type RegressionFit,
+} from "../../stats/regression.ts";
+import { groupBy } from "../../stats/index.ts";
+import { withAlpha } from "../color-utils.ts";
+import type { Aes } from "../aes.ts";
+import { dropNullCategoricalIndices, materialize, resolveAes } from "../aes.ts";
+import type { CompileContext, CompiledHitTest, Geom, ResolvedChannelMap } from "./types.ts";
+import { DEFAULT_CI_LEVEL } from "../constants.ts";
+
+export type SmoothMethod = "lm" | "poly" | "loess";
+
+export interface SmoothChannels<T> {
+  x: Aes<T, number | Date>;
+  y: Aes<T, number>;
+  /** Categorical color channel — fits one curve per group. */
+  color?: Aes<T, unknown>;
+}
+
+export interface SmoothLabelOptions {
+  /** Pixel offset from the right end of the fit. */
+  offsetX?: number;
+  offsetY?: number;
+  /** Custom label color. Defaults to the curve color. */
+  color?: Color;
+  fontSize?: number;
+  /** Optional rounded-rect background. */
+  box?: LabelBoxStyle;
+}
+
+export interface SmoothOptions {
+  /** Fit method. Default `"lm"`. */
+  method?: SmoothMethod;
+  /** Degree for `"poly"` (default `2`) or `"loess"` local polynomial (default `1`). */
+  degree?: number;
+  /** Span for `"loess"` (fraction of data per neighborhood). Default `0.5`. */
+  span?: number;
+  /**
+   * Confidence ribbon. `true` (default) → 95%, `false` → no ribbon, `number`
+   * → that confidence level (e.g. `0.99`).
+   */
+  ci?: boolean | number;
+  /** Number of x samples for the curve & ribbon. Default `64`. */
+  samples?: number;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Override the ribbon fill. Defaults to the stroke color at low alpha. */
+  ribbonFill?: Color;
+  ribbonOpacity?: number;
+  /**
+   * Per-group inline label at the right end of each fitted curve. Only emitted
+   * when the `color` channel is present. `true` uses the group key as the
+   * label string.
+   */
+  label?: boolean | SmoothLabelOptions;
+  /**
+   * When true, hit-tests resolve to the nearest sample by x. Hover anywhere
+   * along the curve and the closest source row in the matching group is
+   * picked. Default `false` (Euclidean within `pickRadius`).
+   */
+  nearestX?: boolean;
+}
+
+interface NumericPair {
+  xs: number[];
+  ys: number[];
+}
+
+function toNumeric<T>(
+  data: readonly T[],
+  xAes: { fn: (d: T, i: number) => unknown },
+  yAes: { fn: (d: T, i: number) => number },
+  rows: readonly number[],
+): NumericPair {
+  const xs: number[] = [];
+  const ys: number[] = [];
+  for (const idx of rows) {
+    const datum = data[idx]!;
+    const xv = xAes.fn(datum, idx);
+    const yv = yAes.fn(datum, idx);
+    const x = xv instanceof Date ? xv.getTime() : (xv as number);
+    if (Number.isFinite(x) && Number.isFinite(yv)) {
+      xs.push(x);
+      ys.push(yv);
+    }
+  }
+  return { xs, ys };
+}
+
+function buildFit(
+  method: SmoothMethod,
+  sample: NumericPair,
+  options: SmoothOptions,
+): RegressionFit | null {
+  if (method === "lm") return linearFit(sample.xs, sample.ys);
+  if (method === "poly") return polyFit(sample.xs, sample.ys, options.degree ?? 2);
+  return loessFit(sample.xs, sample.ys, {
+    span: options.span,
+    degree: (options.degree === 2 ? 2 : 1) as 1 | 2,
+  });
+}
+
+export function smooth<T>(channels: SmoothChannels<T>, options: SmoothOptions = {}): Geom<T> {
+  return {
+    kind: "smooth",
+    channels,
+    compile(ctx: CompileContext<T>) {
+      return compileSmooth(channels, options, ctx);
+    },
+    compileHitTest(ctx: CompileContext<T>): CompiledHitTest<T> | null {
+      const { data, scales, plot } = ctx;
+      if (data.length === 0) return null;
+      const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+      const yAes = resolveAes<T, number>(channels.y);
+      const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+
+      const xScale = scales.x.fn;
+      const yScale = scales.y.fn;
+
+      const groups = buildSmoothGroups(data, colorAes);
+
+      // Upper bound: one hit per source row.
+      const positions = new Float32Array(data.length * 2);
+      const dataIndex = new Int32Array(data.length);
+      const seriesKey: (string | undefined)[] = Array.from({ length: data.length });
+      const ox = plot.topLeft.x;
+      const oy = plot.topLeft.y;
+      let n = 0;
+
+      for (const group of groups) {
+        const sample = toNumeric(data, xAes, yAes, group.rows);
+        const fit = buildFit(options.method ?? "lm", sample, options);
+        if (!fit) continue;
+        const groupSeriesKey = colorAes ? String(group.key) : undefined;
+        for (const idx of group.rows) {
+          const datum = data[idx]!;
+          const xv = xAes.fn(datum, idx);
+          const xNum = xv instanceof Date ? xv.getTime() : (xv as number);
+          if (!Number.isFinite(xNum)) continue;
+          const yhat = fit.predict(xNum);
+          const px = xScale(xv as never);
+          const py = yScale(yhat);
+          if (!Number.isFinite(px) || !Number.isFinite(py)) continue;
+          positions[n * 2] = ox + px;
+          positions[n * 2 + 1] = oy + py;
+          dataIndex[n] = idx;
+          seriesKey[n] = groupSeriesKey;
+          n++;
+        }
+      }
+      if (n === 0) return null;
+
+      const channelsMap: ResolvedChannelMap<T> = {
+        x: xAes,
+        y: yAes as ResolvedChannelMap<T>["y"],
+        color: colorAes,
+      };
+      const strokeWidth = options.strokeWidth ?? ctx.theme.marks.strokeWidth;
+      const pickRadius = options.nearestX
+        ? Math.max(plot.width, plot.height)
+        : Math.max(8, strokeWidth * 2 + 4);
+      return {
+        geomKind: "smooth",
+        positions: positions.subarray(0, n * 2),
+        dataIndex: dataIndex.subarray(0, n),
+        seriesKey: seriesKey.slice(0, n),
+        pickRadius,
+        pickAxis: options.nearestX ? "x" : undefined,
+        channels: channelsMap,
+        data,
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers shared by compile + compileHitTest
+// ---------------------------------------------------------------------------
+
+interface SmoothGroup {
+  key: unknown;
+  rows: number[];
+}
+
+function buildSmoothGroups<T>(
+  data: readonly T[],
+  colorAes: ReturnType<typeof resolveAes<T, unknown>> | undefined,
+): SmoothGroup[] {
+  const indices = Array.from(data, (_d, i) => i);
+  const groups: SmoothGroup[] = [];
+  if (colorAes) {
+    // Null categorical → drop row (see "Null policy" in aes.ts). Keeps the
+    // rendered group set aligned with the categorical color scale's domain.
+    const valid = dropNullCategoricalIndices(indices, colorAes, data);
+    const colorValues = materialize(colorAes, data);
+    for (const [key, rows] of groupBy(valid, (i) => colorValues[i])) {
+      groups.push({ key, rows });
+    }
+  } else {
+    groups.push({ key: undefined, rows: indices });
+  }
+  return groups;
+}
+
+function compileSmooth<T>(
+  channels: SmoothChannels<T>,
+  options: SmoothOptions,
+  ctx: CompileContext<T>,
+) {
+  const { data, scales, plot, theme, atlas } = ctx;
+  const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+  const yAes = resolveAes<T, number>(channels.y);
+  const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+
+  const xScale = scales.x.fn;
+  const yScale = scales.y.fn;
+  const colorScale = scales.color?.fn;
+
+  const method = options.method ?? "lm";
+  const samples = Math.max(2, options.samples ?? 64);
+  const ciOpt = options.ci ?? true;
+  const drawCI = ciOpt !== false;
+  const ciLevel = typeof ciOpt === "number" ? ciOpt : DEFAULT_CI_LEVEL;
+  const baseStroke: Color = options.stroke ?? theme.palettes.categorical(0);
+  const strokeWidth = options.strokeWidth ?? theme.marks.strokeWidth;
+  const ribbonOpacity = options.ribbonOpacity ?? theme.marks.ribbonFillAlpha;
+
+  // Bucket row indices by color group; single bucket when no color channel.
+  const indices = Array.from(data, (_d, i) => i);
+  const groups: { key: unknown; rows: number[] }[] = [];
+  if (colorAes) {
+    const colorValues = materialize(colorAes, data);
+    for (const [key, rows] of groupBy(indices, (i) => colorValues[i])) {
+      groups.push({ key, rows });
+    }
+  } else {
+    groups.push({ key: undefined, rows: indices });
+  }
+
+  const labelEnabled =
+    options.label !== undefined && options.label !== false && colorAes !== undefined;
+  const labelOpts: SmoothLabelOptions = typeof options.label === "object" ? options.label : {};
+  const labelOffsetX = labelOpts.offsetX ?? -4;
+  const labelOffsetY = labelOpts.offsetY ?? -10;
+  const labelFontSize = labelOpts.fontSize ?? theme.marks.annotationFontSize;
+
+  const builders: ReturnType<typeof wrapMark>[] = [];
+
+  for (const group of groups) {
+    if (ctx.hidden && colorAes && ctx.hidden.has(String(group.key))) continue;
+    const sample = toNumeric(data, xAes, yAes, group.rows);
+    const fit = buildFit(method, sample, options);
+    if (!fit) continue;
+
+    const groupColor = colorScale && colorAes ? colorScale(group.key) : baseStroke;
+    const ribbonFill =
+      options.ribbonFill ?? withAlpha(groupColor, (groupColor.a ?? 1) * ribbonOpacity);
+
+    const xMin = sample.xs.length > 0 ? Math.min(...sample.xs) : 0;
+    const xMax = sample.xs.length > 0 ? Math.max(...sample.xs) : 1;
+    const band = drawCI
+      ? confidenceBand(fit, sample.xs, {
+          samples,
+          level: ciLevel,
+          domain: [xMin, xMax],
+        })
+      : null;
+
+    // Build the curve point series first — used for the line and (when no
+    // CI) standalone. Re-derive from `band` if available so points line up.
+    const curve = band
+      ? band.map((p) => ({ x: p.x, yhat: p.yhat }))
+      : (() => {
+          const out: { x: number; yhat: number }[] = Array.from({ length: samples });
+          const step = (xMax - xMin) / (samples - 1);
+          for (let i = 0; i < samples; i++) {
+            const x = xMin + step * i;
+            out[i] = { x, yhat: fit.predict(x) };
+          }
+          return out;
+        })();
+
+    if (band) {
+      const ribbonPoints = band.map((p) => p);
+      const ribbon = areaMark(ribbonPoints, {
+        x: (p) => xScale(p.x),
+        y0: (p) => yScale(p.lo),
+        y1: (p) => yScale(p.hi),
+        fill: ribbonFill,
+      });
+      builders.push(wrapMark(ribbon, plot.topLeft, ribbonPoints.length));
+    }
+
+    const line = lineMark(curve, {
+      x: (p) => xScale(p.x),
+      y: (p) => yScale(p.yhat),
+      stroke: groupColor,
+      strokeWidth,
+    });
+    builders.push(wrapMark(line, plot.topLeft, curve.length));
+
+    if (labelEnabled && atlas) {
+      const last = curve[curve.length - 1]!;
+      const labelText = String(group.key);
+      const labelMark = valueLabelMark([last], {
+        x: (p) => xScale(p.x),
+        y: (p) => yScale(p.yhat),
+        text: () => labelText,
+        fontSize: labelFontSize,
+        color: labelOpts.color ?? groupColor,
+        align: "right",
+        offset: { x: labelOffsetX, y: labelOffsetY },
+        box: labelOpts.box,
+        atlas,
+      });
+      builders.push(wrapMark(labelMark, plot.topLeft, 1));
+    }
+  }
+
+  return builders;
+}

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

@@ -0,0 +1,29 @@
+import type { Color } from "insomni";
+import { type LabelBoxStyle, type ValueLabelAlign } from "../../annotations.ts";
+import type { Aes } from "../aes.ts";
+import type { Geom } from "./types.ts";
+export type TextCollisionMode = "none" | "hide" | "stagger";
+export interface TextChannels<T> {
+    x: Aes<T, number | Date | string>;
+    y: Aes<T, number | Date | string>;
+    text: Aes<T, string>;
+}
+export interface TextOptions {
+    fontSize?: number;
+    color?: Color;
+    align?: ValueLabelAlign;
+    offsetX?: number;
+    offsetY?: number;
+    /** Optional rounded-rect background. Requires the chart's glyph atlas. */
+    box?: LabelBoxStyle;
+    label?: string;
+    /**
+     * Post-layout collision handling. Default `"none"`. `"hide"` drops
+     * overlapping labels via a greedy first-fit pass; `"stagger"` adds an
+     * alternating y offset so adjacent labels sit on two rows.
+     */
+    collisionMode?: TextCollisionMode;
+    /** Pixel padding around each label's measured rect when checking overlap. Default `2`. */
+    collisionPadding?: number;
+}
+export declare function text<T>(channels: TextChannels<T>, options?: TextOptions): Geom<T>;

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

@@ -0,0 +1,64 @@
+import { createFrame } from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+
+import { resolveAes } from "../aes.ts";
+import { buildPositionScale, type ScaleBundle } from "../scales.ts";
+import { themeDefault } from "../theme.ts";
+import { text } from "./text.ts";
+import type { CompileContext } from "./types.ts";
+
+interface Row {
+  x: number;
+  y: number;
+  label: string;
+}
+
+const data: Row[] = [
+  { x: 0, y: 10, label: "alpha" },
+  { x: 50, y: 20, label: "beta" },
+  { x: 100, y: 30, label: "gamma" },
+];
+
+function makeCtx(rows: readonly Row[]): CompileContext<Row> {
+  const xAes = resolveAes<Row, unknown>("x");
+  const yAes = resolveAes<Row, unknown>("y");
+  const xScale = buildPositionScale(xAes, rows, [0, 100]);
+  const yScale = buildPositionScale(yAes, rows, [200, 0]);
+  const scales: ScaleBundle = { x: xScale, y: yScale };
+  return {
+    data: rows,
+    scales,
+    plot: createFrame({ x: 50, y: 30, width: 100, height: 200 }),
+    theme: themeDefault,
+    atlas: undefined,
+  };
+}
+
+describe("text geom — compileHitTest", () => {
+  test("emits one hit per row at scaled (x, y) absolute coords", () => {
+    const geom = text<Row>({ x: "x", y: "y", text: "label" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(hits.geomKind).toBe("text");
+    expect(hits.dataIndex.length).toBe(3);
+    // First row: x=0 → range start 0, +plot.x(50). y=10 → domain [10,30], range [200,0],
+    // 10 → 200. +plot.y(30) = 230.
+    expect(hits.positions[0]).toBeCloseTo(50, 3);
+    expect(hits.positions[1]).toBeCloseTo(230, 3);
+    expect(hits.dataIndex[0]).toBe(0);
+    expect(hits.dataIndex[2]).toBe(2);
+  });
+
+  test("text content is exposed via channels for tooltip rows", () => {
+    const geom = text<Row>({ x: "x", y: "y", text: "label" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    const shapeAes = hits.channels.shape;
+    expect(shapeAes).toBeDefined();
+    expect(shapeAes!.column).toBe("text");
+    expect(shapeAes!.fn(data[1]!, 1)).toBe("beta");
+  });
+
+  test("returns null on empty data", () => {
+    const geom = text<Row>({ x: "x", y: "y", text: "label" });
+    expect(geom.compileHitTest!(makeCtx([]))).toBeNull();
+  });
+});