insomni-plot 0.1.0-alpha.0

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

@@ -0,0 +1,216 @@
+// ---------------------------------------------------------------------------
+// Polar smoke tests for generic plot geoms (Phase 3b).
+// ---------------------------------------------------------------------------
+// These tests pin the polar projection behavior of `point`, `text`, `line`,
+// `rule`, and `tile` under a known `coordPolar({...})` config. The goal is
+// to catch regressions in:
+//
+//   1. Per-vertex projection (point / text): hit-test positions land on the
+//      visible mark, not at the unprojected plot-frame coords.
+//   2. Per-segment tessellation (line): consecutive vertices generate more
+//      than two points in the emitted polyline (arc samples), not a single
+//      chord.
+//   3. Polar-correct rule shape: a constant-x rule becomes a closed
+//      multi-sample arc (circle for full y), not a 2-point line.
+//   4. Tile gracefully throws the friendly polar-unsupported error.
+//
+// We pick a 200 × 200 plot frame so the polar centre is at (100, 100) in
+// plot-frame space, and the outerRadius defaults to 100. With
+// `startAngle: -π/2`, a point at the *top* of the data domain (max y under
+// the default `angleChannel: 'y'`) projects to (cx, cy - outerR) = (100, 0)
+// in plot-frame px (plus the plot origin for hit positions).
+
+import { createFrame } from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+
+import { resolveAes } from "../aes.ts";
+import { coordPolar, type Coord } from "../coord.ts";
+import { buildPositionScale, type ScaleBundle } from "../scales.ts";
+import { themeDefault } from "../theme.ts";
+import { line } from "./line.ts";
+import { point } from "./point.ts";
+import { rule } from "./rule.ts";
+import { tile } from "./tile.ts";
+import type { CompileContext } from "./types.ts";
+
+interface Row {
+  x: number;
+  y: number;
+}
+
+const PLOT_X = 50;
+const PLOT_Y = 30;
+const PLOT_W = 200;
+const PLOT_H = 200;
+
+function makePolarCoord(): Coord {
+  const c = coordPolar({
+    startAngle: -Math.PI / 2,
+    openAngle: 0,
+    direction: 1,
+    angleChannel: "y",
+  });
+  c.bindFrame(createFrame({ x: 0, y: 0, width: PLOT_W, height: PLOT_H }));
+  return c;
+}
+
+function makeCtx<T extends Row>(rows: readonly T[]): CompileContext<T> {
+  const xAes = resolveAes<T, unknown>("x");
+  const yAes = resolveAes<T, unknown>("y");
+  // x scale: data [0, 1] → px [0, PLOT_W] (radius channel)
+  // y scale: data [0, 1] → px [PLOT_H, 0]  (angle channel, flipped per plot
+  // convention so y=1 lands at the top)
+  const xScale = buildPositionScale(xAes, rows, [0, PLOT_W], { domain: [0, 1] });
+  const yScale = buildPositionScale(yAes, rows, [PLOT_H, 0], { domain: [0, 1] });
+  const scales: ScaleBundle = { x: xScale, y: yScale };
+  return {
+    data: rows,
+    scales,
+    plot: createFrame({ x: PLOT_X, y: PLOT_Y, width: PLOT_W, height: PLOT_H }),
+    theme: themeDefault,
+    atlas: undefined,
+    coord: makePolarCoord(),
+  };
+}
+
+describe("polar — point geom", () => {
+  test("hit-test positions project through coord, not the raw plot-frame px", () => {
+    // y = 1 maps to plot-frame y=0 (top of plot). Under polar with
+    // startAngle=-π/2, angleChannel=y, the angle is computed from
+    // `plotH - p.y = 200`, so t = 200/200 = 1, theta = -π/2 + 2π = 3π/2 ≡ -π/2.
+    // r at x=1: t=1, r = outerR = 100.
+    // Projected (in plot-frame px): (cx + r·cos(-π/2), cy + r·sin(-π/2))
+    //                              = (100 + 0, 100 - 100) = (100, 0).
+    // Absolute hit position: (PLOT_X + 100, PLOT_Y + 0) = (150, 30).
+    const geom = point<Row>({ x: "x", y: "y" });
+    const hits = geom.compileHitTest!(makeCtx([{ x: 1, y: 1 }]))!;
+    expect(hits.dataIndex.length).toBe(1);
+    expect(hits.positions[0]).toBeCloseTo(PLOT_X + 100, 1);
+    expect(hits.positions[1]).toBeCloseTo(PLOT_Y + 0, 1);
+  });
+
+  test("inner radius point at x=0 projects to the polar centre", () => {
+    // x = 0 → r = 0 → projected = (cx, cy) = (100, 100); absolute (150, 130).
+    const geom = point<Row>({ x: "x", y: "y" });
+    const hits = geom.compileHitTest!(makeCtx([{ x: 0, y: 0.5 }]))!;
+    expect(hits.positions[0]).toBeCloseTo(PLOT_X + 100, 1);
+    expect(hits.positions[1]).toBeCloseTo(PLOT_Y + 100, 1);
+  });
+});
+
+describe("polar — line geom", () => {
+  test("emits an arc-tessellated polyline between vertices on the same radius", () => {
+    // Two points at the same x (r=outerR=100) but at different y (different
+    // θ). Picking y=0 vs y=0.5 gives a half-circle sweep — the segment
+    // tessellator should emit ~180 samples (one per ~1°).
+    //
+    // We deliberately avoid the full sweep (0 → 1) because under full-circle
+    // polar the endpoints are the same physical point (start == end), which
+    // would degenerate to a 2-point segment.
+    const polylines: { points: readonly { x: number; y: number }[] }[] = [];
+    const layer = {
+      pushPolyline(shape: { points: readonly { x: number; y: number }[] }) {
+        polylines.push({ points: [...shape.points] });
+      },
+    };
+    const ctx = makeCtx<Row>([
+      { x: 1, y: 0 },
+      { x: 1, y: 0.5 },
+    ]);
+    const geom = line<Row>({ x: "x", y: "y" });
+    const builders = geom.compile(ctx);
+    for (const b of builders) b.addTo(layer as never);
+    expect(polylines).toHaveLength(1);
+    // Half-circle sweep at ~1° step → roughly 180 samples (well over 50).
+    expect(polylines[0]!.points.length).toBeGreaterThan(50);
+    // All samples should lie on a circle of radius `outerR` around the
+    // polar centre (cx, cy) = (PLOT_X + 100, PLOT_Y + 100).
+    for (const p of polylines[0]!.points) {
+      const dx = p.x - (PLOT_X + 100);
+      const dy = p.y - (PLOT_Y + 100);
+      const r = Math.hypot(dx, dy);
+      expect(r).toBeCloseTo(100, 0);
+    }
+  });
+
+  test("cartesian path is unchanged when ctx.coord is omitted", () => {
+    // Sanity: make a non-polar ctx and confirm we still get a 3-point chord.
+    const xAes = resolveAes<Row, unknown>("x");
+    const yAes = resolveAes<Row, unknown>("y");
+    const xScale = buildPositionScale(xAes, [], [0, 100], { domain: [0, 1] });
+    const yScale = buildPositionScale(yAes, [], [200, 0], { domain: [0, 1] });
+    const ctx: CompileContext<Row> = {
+      data: [
+        { x: 0, y: 0 },
+        { x: 0.5, y: 0.5 },
+        { x: 1, y: 1 },
+      ],
+      scales: { x: xScale, y: yScale },
+      plot: createFrame({ x: 50, y: 30, width: 100, height: 200 }),
+      theme: themeDefault,
+      atlas: undefined,
+      // No coord → defaults to cartesian.
+    };
+    const polylines: { points: readonly { x: number; y: number }[] }[] = [];
+    const layer = {
+      pushPolyline(shape: { points: readonly { x: number; y: number }[] }) {
+        polylines.push({ points: [...shape.points] });
+      },
+    };
+    const geom = line<Row>({ x: "x", y: "y" });
+    const builders = geom.compile(ctx);
+    for (const b of builders) b.addTo(layer as never);
+    expect(polylines).toHaveLength(1);
+    expect(polylines[0]!.points.length).toBe(3);
+  });
+});
+
+describe("polar — rule geom", () => {
+  test("vertical rule at constant x emits an arc polyline (circle for full y)", () => {
+    const polylines: { points: readonly { x: number; y: number }[] }[] = [];
+    const layer = {
+      pushPolyline(shape: { points: readonly { x: number; y: number }[] }) {
+        polylines.push({ points: [...shape.points] });
+      },
+    };
+    const geom = rule<Row>({ x: 0.5 });
+    const ctx = makeCtx<Row>([{ x: 0.5, y: 0 }]);
+    const builders = geom.compile(ctx);
+    for (const b of builders) b.addTo(layer as never);
+    expect(polylines).toHaveLength(1);
+    // r at x=0.5: t=0.5, r = 50. Full sweep → many samples on a circle of
+    // radius 50 around the polar centre.
+    expect(polylines[0]!.points.length).toBeGreaterThan(100);
+    for (const p of polylines[0]!.points) {
+      const dx = p.x - (PLOT_X + 100);
+      const dy = p.y - (PLOT_Y + 100);
+      const r = Math.hypot(dx, dy);
+      expect(r).toBeCloseTo(50, 0);
+    }
+  });
+
+  test("horizontal rule at constant y emits a 2-point spoke (constant θ)", () => {
+    const polylines: { points: readonly { x: number; y: number }[] }[] = [];
+    const layer = {
+      pushPolyline(shape: { points: readonly { x: number; y: number }[] }) {
+        polylines.push({ points: [...shape.points] });
+      },
+    };
+    const geom = rule<Row>({ y: 0.5 });
+    const ctx = makeCtx<Row>([{ x: 0, y: 0.5 }]);
+    const builders = geom.compile(ctx);
+    for (const b of builders) b.addTo(layer as never);
+    expect(polylines).toHaveLength(1);
+    // y=0.5 fixes θ, so coord.segment shortcuts to a 2-point straight spoke.
+    expect(polylines[0]!.points.length).toBe(2);
+  });
+});
+
+describe("polar — tile geom", () => {
+  test("throws a friendly error under polar (v1 unsupported)", () => {
+    const geom = tile<Row>({ x: "x", y: "y" });
+    expect(() => geom.compile(makeCtx<Row>([{ x: 0.5, y: 0.5 }]))).toThrow(
+      /coordPolar.*does not support geomTile/,
+    );
+  });
+});

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

@@ -0,0 +1,21 @@
+import type { Aes } from "../aes.ts";
+import { type ColorOrAccent } from "../color-utils.ts";
+import type { Geom } from "./types.ts";
+export interface RibbonChannels<T> {
+    x: Aes<T, number | Date>;
+    y0: Aes<T, number | Date>;
+    y1: Aes<T, number | Date>;
+}
+export interface RibbonOptions {
+    /**
+     * Fill color. Accepts a literal {@link Color} or a theme accent key
+     * (`"positive" | "negative" | "warn" | "info"`); accent keys resolve through
+     * `theme.accents`.
+     */
+    fill?: ColorOrAccent;
+    stroke?: ColorOrAccent;
+    strokeWidth?: number;
+    fillAlpha?: number;
+    label?: string;
+}
+export declare function ribbon<T>(channels: RibbonChannels<T>, options?: RibbonOptions): Geom<T>;

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

@@ -0,0 +1,170 @@
+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 { ribbon } from "./ribbon.ts";
+import type { CompileContext } from "./types.ts";
+
+interface Row {
+  x: number;
+  lo: number;
+  hi: number;
+}
+
+const data: Row[] = [
+  { x: 0, lo: 2, hi: 8 },
+  { x: 5, lo: 3, hi: 10 },
+  { x: 10, lo: 1, hi: 12 },
+];
+
+// y1 ("hi") is the only registered position channel, so the y position scale is
+// built off `hi`. The domain spans 8..12 from `hi` alone.
+function makeCtx(rows: readonly Row[], yDomain?: [number, number]): CompileContext<Row> {
+  const xAes = resolveAes<Row, unknown>("x");
+  const yAes = resolveAes<Row, unknown>("hi");
+  const xScale = buildPositionScale(xAes, rows, [0, 100]);
+  const yScale = buildPositionScale(
+    yAes,
+    rows,
+    [200, 0],
+    yDomain ? { domain: yDomain } : undefined,
+  );
+  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,
+  };
+}
+
+function capturePolygons(
+  ctx: CompileContext<Row>,
+  geom = ribbon<Row>({ x: "x", y0: "lo", y1: "hi" }),
+): Array<{ points: Array<{ x: number; y: number }>; fill?: unknown; stroke?: unknown }> {
+  const polygons: Array<{ points: Array<{ x: number; y: number }>; fill?: unknown }> = [];
+  const layer = {
+    pushPolygon(shape: { points: Array<{ x: number; y: number }> }) {
+      polygons.push(shape);
+    },
+    pushPolyline() {},
+  };
+  for (const b of geom.compile(ctx)) b.addTo(layer as never);
+  return polygons;
+}
+
+describe("ribbon geom — contract", () => {
+  test("shares kind 'area' so it reuses the area legend swatch", () => {
+    const geom = ribbon<Row>({ x: "x", y0: "lo", y1: "hi" });
+    expect(geom.kind).toBe("area");
+    expect(typeof geom.legendSwatch).toBe("function");
+  });
+
+  test("registers only x and y1 as channels (y0 is internal)", () => {
+    const geom = ribbon<Row>({ x: "x", y0: "lo", y1: "hi" });
+    expect(geom.channels.x).toBe("x");
+    expect(geom.channels.y).toBe("hi");
+  });
+
+  test("passes through an explicit label", () => {
+    const geom = ribbon<Row>({ x: "x", y0: "lo", y1: "hi" }, { label: "CI band" });
+    expect(geom.label).toBe("CI band");
+  });
+});
+
+describe("ribbon geom — prepareDomain", () => {
+  test("y extend spans both the lower and upper bounds", () => {
+    const geom = ribbon<Row>({ x: "x", y0: "lo", y1: "hi" });
+    const hints = geom.prepareDomain!(data);
+    // lo min = 1, hi max = 12 → union [1, 12].
+    expect(hints?.y?.extend).toEqual([1, 12]);
+  });
+
+  test("a lower bound below the y1-derived domain is still included", () => {
+    // hi alone is 8..12; lo reaches down to -5 and must widen the extend.
+    const rows: Row[] = [
+      { x: 0, lo: -5, hi: 8 },
+      { x: 10, lo: 0, hi: 12 },
+    ];
+    const geom = ribbon<Row>({ x: "x", y0: "lo", y1: "hi" });
+    const hints = geom.prepareDomain!(rows);
+    expect(hints?.y?.extend).toEqual([-5, 12]);
+  });
+
+  test("ignores non-finite bounds", () => {
+    const rows: Row[] = [
+      { x: 0, lo: NaN, hi: 8 },
+      { x: 10, lo: 2, hi: NaN },
+    ];
+    const geom = ribbon<Row>({ x: "x", y0: "lo", y1: "hi" });
+    const hints = geom.prepareDomain!(rows);
+    expect(hints?.y?.extend).toEqual([2, 8]);
+  });
+
+  test("empty data yields no hint", () => {
+    const geom = ribbon<Row>({ x: "x", y0: "lo", y1: "hi" });
+    expect(geom.prepareDomain!([])).toBeUndefined();
+  });
+
+  test("all-non-finite data yields no hint", () => {
+    const rows: Row[] = [{ x: 0, lo: NaN, hi: NaN }];
+    const geom = ribbon<Row>({ x: "x", y0: "lo", y1: "hi" });
+    expect(geom.prepareDomain!(rows)).toBeUndefined();
+  });
+});
+
+describe("ribbon geom — compile", () => {
+  test("emits a single filled polygon: top edge (y1) then bottom edge (y0) reversed", () => {
+    // Pin the y domain to [0, 20] so pixel positions are predictable.
+    const ctx = makeCtx(data, [0, 20]);
+    const polygons = capturePolygons(ctx);
+    expect(polygons).toHaveLength(1);
+    const pts = polygons[0]!.points;
+    // 3 rows → top(3) + bottom(3) = 6 vertices.
+    expect(pts).toHaveLength(6);
+
+    // x: 0,5,10 over [0,10] → [0,100] → 0,50,100; +plot.x(50) = 50,100,150.
+    // Top edge is hi values left→right at x = 50,100,150.
+    expect(pts.slice(0, 3).map((p) => p.x)).toEqual([50, 100, 150]);
+    // y(hi): 8,10,12 over [0,20] → [200,0] → 120,100,80; +plot.y(30) = 150,130,110.
+    expect(pts.slice(0, 3).map((p) => p.y)).toEqual([150, 130, 110]);
+
+    // Bottom edge is lo values right→left at x = 150,100,50.
+    expect(pts.slice(3).map((p) => p.x)).toEqual([150, 100, 50]);
+    // y(lo): rows reversed → lo = 1,3,2 → over [0,20] → [200,0] → 190,170,180;
+    // +plot.y(30) = 220,200,210.
+    expect(pts.slice(3).map((p) => p.y)).toEqual([220, 200, 210]);
+  });
+
+  test("applies an alphaized fill", () => {
+    const polygons = capturePolygons(makeCtx(data, [0, 20]));
+    expect(polygons[0]!.fill).toBeDefined();
+  });
+
+  test("lower == upper collapses to a degenerate (zero-height) band", () => {
+    const flat: Row[] = [
+      { x: 0, lo: 5, hi: 5 },
+      { x: 10, lo: 5, hi: 5 },
+    ];
+    const ctx = makeCtx(flat, [0, 10]);
+    const polygons = capturePolygons(ctx);
+    expect(polygons).toHaveLength(1);
+    const pts = polygons[0]!.points;
+    expect(pts).toHaveLength(4);
+    // y(5) over [0,10] → [200,0] → 100; +plot.y(30) = 130. Top and bottom share it.
+    expect(pts.every((p) => p.y === 130)).toBe(true);
+  });
+
+  test("a single datum produces no polygon (needs >= 2 points to fill)", () => {
+    const single: Row[] = [{ x: 0, lo: 2, hi: 8 }];
+    const polygons = capturePolygons(makeCtx(single, [0, 20]));
+    expect(polygons).toHaveLength(0);
+  });
+
+  test("empty data produces no polygon", () => {
+    expect(capturePolygons(makeCtx([], [0, 20]))).toHaveLength(0);
+  });
+});

package/src/grammar/geoms/ribbon.ts

@@ -0,0 +1,87 @@
+// ---------------------------------------------------------------------------
+// ribbon geom — area between y0 and y1
+// ---------------------------------------------------------------------------
+
+import { areaMark } from "../../marks.ts";
+import type { Aes } from "../aes.ts";
+import { resolveAes } from "../aes.ts";
+import { alphaize, resolveAccent, type ColorOrAccent } from "../color-utils.ts";
+import { areaSwatch } from "../../legend.ts";
+import type { CompileContext, Geom, ScaleHints } from "./types.ts";
+import { wrapMark } from "./_mark.ts";
+
+export interface RibbonChannels<T> {
+  x: Aes<T, number | Date>;
+  y0: Aes<T, number | Date>;
+  y1: Aes<T, number | Date>;
+}
+
+export interface RibbonOptions {
+  /**
+   * Fill color. Accepts a literal {@link Color} or a theme accent key
+   * (`"positive" | "negative" | "warn" | "info"`); accent keys resolve through
+   * `theme.accents`.
+   */
+  fill?: ColorOrAccent;
+  stroke?: ColorOrAccent;
+  strokeWidth?: number;
+  fillAlpha?: number;
+  label?: string;
+}
+
+export function ribbon<T>(channels: RibbonChannels<T>, options: RibbonOptions = {}): Geom<T> {
+  return {
+    // Shares `kind: "area"` with `area()` so the auto-legend reuses the area
+    // swatch — both render as filled regions with the same visual semantics.
+    kind: "area",
+    channels: { x: channels.x, y: channels.y1 },
+    label: options.label,
+    legendSwatch: (color) => areaSwatch({ fill: color, width: 14, height: 10 }),
+    prepareDomain(data) {
+      // Only y1 is registered as a channel, so the pipeline never sees y0.
+      // Union both into a single extend hint so a y0 below the y1-derived
+      // domain is still visible.
+      const y0Aes = resolveAes<T, unknown>(channels.y0 as Aes<T, unknown>);
+      const y1Aes = resolveAes<T, unknown>(channels.y1 as Aes<T, unknown>);
+      let lo = Number.POSITIVE_INFINITY;
+      let hi = Number.NEGATIVE_INFINITY;
+      for (let i = 0; i < data.length; i++) {
+        const datum = data[i]!;
+        const a = y0Aes.fn(datum, i);
+        const b = y1Aes.fn(datum, 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;
+        }
+      }
+      if (!Number.isFinite(lo) || !Number.isFinite(hi)) return undefined;
+      const hints: ScaleHints = { y: { extend: [lo, hi] } };
+      return hints;
+    },
+    compile(ctx: CompileContext<T>) {
+      const { data, scales, plot, theme } = ctx;
+      const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+      const y0Aes = resolveAes<T, unknown>(channels.y0 as Aes<T, unknown>);
+      const y1Aes = resolveAes<T, unknown>(channels.y1 as Aes<T, unknown>);
+      const xFn = scales.x.fn;
+      const yFn = scales.y.fn;
+      const fill = resolveAccent(options.fill, theme) ?? theme.palettes.categorical(0);
+      const alpha = options.fillAlpha ?? theme.marks.ribbonFillAlpha;
+      const mark = areaMark(data, {
+        x: (d, i) => xFn(xAes.fn(d, i)),
+        y0: (d, i) => yFn(y0Aes.fn(d, i)),
+        y1: (d, i) => yFn(y1Aes.fn(d, i)),
+        fill: alphaize(fill, alpha),
+        stroke: resolveAccent(options.stroke, theme),
+        strokeWidth: options.strokeWidth,
+      });
+      return [wrapMark(mark, plot.topLeft, data.length)];
+    },
+  };
+}

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

@@ -0,0 +1,89 @@
+import type { Color } from "insomni";
+import { type BinClosed, type BinRule, type HistogramMeasure, type KdeBandwidth, type KdeKernel, type QuantileMethod, type WhiskerRule } from "../../stats/index.ts";
+import { type Aes } from "../aes.ts";
+import type { Geom } from "./types.ts";
+import { type CategoricalLayout } from "./_categorical.ts";
+import { type DensityScale } from "./_distribution.ts";
+export type RidgelineGeom = "kde" | "histogram";
+export type RidgelineScale = DensityScale;
+export type RidgelineInner = "none" | "median" | "quartile" | "mean";
+export type RidgelineFillMode = "solid" | "gradient";
+export interface RidgelineChannels<T> {
+    /** Numeric value being distributed. Provide one of x or y; the other is the row category. */
+    x: Aes<T, string | number>;
+    y: Aes<T, string | number>;
+    /** Optional categorical group key. Drives palette fill (chart color scale). */
+    color?: Aes<T, unknown>;
+}
+export interface RidgelineOptions {
+    /** Auto-detected from scale types when omitted. The default reproduces the common "rows on y, values on x" layout. */
+    orientation?: "x" | "y";
+    /** Density estimator. Default `"kde"`. */
+    geom?: RidgelineGeom;
+    /**
+     * How tall a ridge can be relative to its band-cell spacing. `1` = no
+     * overlap (each ridge stays inside its row); `>1` allows overlap into
+     * neighbours. Default `2.5`.
+     */
+    overlap?: number;
+    /**
+     * Across-group height normalization (same semantics as `violin`'s `scale`).
+     *
+     * - `"width"` (default) — each row uses its full allotted height.
+     * - `"area"` — heights normalized by the global max density.
+     * - `"count"` — heights scaled by sample size on top of `"area"`.
+     */
+    scale?: RidgelineScale;
+    bandwidth?: KdeBandwidth;
+    gridSize?: number;
+    kernel?: KdeKernel;
+    trim?: boolean;
+    bins?: number;
+    binwidth?: number;
+    breaks?: readonly number[];
+    rule?: BinRule;
+    measure?: HistogramMeasure;
+    closed?: BinClosed;
+    /**
+     * Solid fill (default) uses the chart color scale per category, or the
+     * theme's categorical palette if no `color` channel is mapped. Gradient
+     * fill ignores the category and applies a value-axis-mapped color ramp,
+     * reproducing the "Lincoln NE temperatures" look.
+     */
+    fillMode?: RidgelineFillMode;
+    /**
+     * Color ramp for `fillMode: "gradient"`. Receives `t ∈ [0, 1]` mapped from
+     * the value-axis range. Default = `theme.palettes.continuous`.
+     */
+    gradient?: (t01: number) => Color;
+    /** Per-row inner annotation. Default `"none"`. */
+    inner?: RidgelineInner;
+    innerStroke?: Color;
+    innerStrokeWidth?: number;
+    /** Radius of the median/mean dot when `inner` includes a point. Default `3`. */
+    innerDotRadius?: number;
+    /** Draw a thin rule along each row's baseline. Default `true`. */
+    baseline?: boolean;
+    baselineStroke?: Color;
+    baselineWidth?: number;
+    /** `n=<count>` per row, anchored inline at the row baseline by default. */
+    showCounts?: boolean;
+    countsAnchor?: "outside" | "inline";
+    /** Pixel offset for the counts label. Default 4 (inline) / 28 (outside, vertical) / 32 (outside, horizontal). */
+    countsOffset?: number;
+    countsFontSize?: number;
+    countsColor?: Color;
+    /** Solid fill for the silhouette. Default theme palette[0] (overridden by chart color scale when `color` is set). */
+    fill?: Color;
+    fillAlpha?: number;
+    /** Silhouette outline. Default theme text color. */
+    stroke?: Color;
+    strokeWidth?: number;
+    /** Inner-band padding when dodging via `color`. Default `0.05`. */
+    groupPadding?: number;
+    whisker?: WhiskerRule;
+    quantile?: QuantileMethod;
+    label?: string;
+}
+export declare function ridgeline<T>(channels: RidgelineChannels<T>, options?: RidgelineOptions): Geom<T>;
+export type { CategoricalLayout };