insomni-plot 0.1.0-alpha.0

package/src/grammar/facet.d.ts

@@ -0,0 +1,63 @@
+import { type Color, type Frame, type Layer } from "insomni";
+import type { Aes } from "./aes.ts";
+import type { Theme } from "./theme.ts";
+export type FacetScales = "fixed" | "free";
+export interface FacetStripStyle {
+    height?: number;
+    fontSize?: number;
+    color?: Color;
+    background?: Color;
+}
+export interface FacetSpec<T> {
+    /** Accessor / column name producing the facet key per datum. */
+    by: Aes<T, unknown>;
+    /** Number of columns. Default: ceil(sqrt(n)). */
+    ncol?: number;
+    /** Number of rows. Default: ceil(n / ncol). */
+    nrow?: number;
+    /**
+     * Scale handling across panels.
+     * - `"fixed"` (default) — every panel shares the same x/y/color/… scales.
+     * - `"free"` — each panel computes its own scales from its data.
+     */
+    scales?: FacetScales;
+    /** Spacing between panels in pixels. Default `12`. */
+    gap?: number;
+    /** Strip header style. */
+    strip?: FacetStripStyle;
+    /** Optional formatter for the strip label. */
+    format?: (key: unknown) => string;
+}
+export interface FacetPanel<T> {
+    key: unknown;
+    rows: T[];
+    /** Index into the column-major grid. */
+    col: number;
+    row: number;
+    /** Sub-frame within the chart's plot frame. */
+    frame: Frame;
+    /** True for the leftmost column — render y-axis only here. */
+    isLeftCol: boolean;
+    /** True for the bottom row of *populated* panels — render x-axis only here. */
+    isBottomRow: boolean;
+}
+export interface FacetLayout<T> {
+    panels: FacetPanel<T>[];
+    ncol: number;
+    nrow: number;
+    stripHeight: number;
+}
+export declare function groupForFacet<T>(spec: FacetSpec<T>, data: readonly T[]): {
+    key: unknown;
+    rows: T[];
+}[];
+/**
+ * Slice the chart's plot frame into a grid of panel sub-frames. Each sub-frame
+ * contains a strip header at the top and a panel body underneath.
+ */
+export declare function computeFacetLayout<T>(spec: FacetSpec<T>, groups: readonly {
+    key: unknown;
+    rows: T[];
+}[], plot: Frame): FacetLayout<T>;
+/** Draw a strip header above a panel frame. */
+export declare function renderFacetStrip(layer: Layer, panel: FacetPanel<unknown>, spec: FacetSpec<unknown>, theme: Theme): void;

package/src/grammar/facet.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "vite-plus/test";
+import { viewportFrame } from "insomni";
+
+import { computeFacetLayout, groupForFacet, type FacetSpec } from "./facet.ts";
+
+interface Row {
+  group: string;
+  v: number;
+}
+
+const DATA: Row[] = [
+  { group: "a", v: 1 },
+  { group: "b", v: 2 },
+  { group: "a", v: 3 },
+  { group: "c", v: 4 },
+  { group: "b", v: 5 },
+];
+
+describe("facet", () => {
+  test("groupForFacet preserves first-occurrence order", () => {
+    const groups = groupForFacet({ by: "group" }, DATA);
+    expect(groups.map((g) => g.key)).toEqual(["a", "b", "c"]);
+    expect(groups[0]!.rows).toHaveLength(2);
+    expect(groups[1]!.rows).toHaveLength(2);
+    expect(groups[2]!.rows).toHaveLength(1);
+  });
+
+  test("computeFacetLayout splits the plot frame into ncol×nrow panels", () => {
+    const groups = groupForFacet({ by: "group" }, DATA);
+    const plot = viewportFrame(400, 300);
+    const spec: FacetSpec<Row> = { by: "group", ncol: 2, gap: 10, scales: "fixed" };
+    const layout = computeFacetLayout(spec, groups, plot);
+    expect(layout.ncol).toBe(2);
+    expect(layout.nrow).toBe(2);
+    expect(layout.panels).toHaveLength(3);
+
+    // Expected panel sizes — the gap takes 10px per inner row/col, strip eats
+    // the top of every panel.
+    const panelW = (400 - 10) / 2;
+    expect(layout.panels[0]!.frame.width).toBeCloseTo(panelW, 5);
+    expect(layout.panels[0]!.frame.x).toBeCloseTo(0, 5);
+    expect(layout.panels[1]!.frame.x).toBeCloseTo(panelW + 10, 5);
+  });
+
+  test("isBottomRow flags the last populated row in each column", () => {
+    // Five panels in a 2-col grid → row 2 has only column 0.
+    const data = ["a", "b", "c", "d", "e"].map((k) => ({ group: k, v: 0 }));
+    const groups = groupForFacet({ by: "group" }, data);
+    const plot = viewportFrame(400, 300);
+    const layout = computeFacetLayout({ by: "group", ncol: 2 }, groups, plot);
+    const flags = layout.panels.map((p) => p.isBottomRow);
+    // Column 0's bottom panel is index 4 (row 2). Column 1's bottom panel is
+    // index 3 (row 1).
+    expect(flags[0]).toBe(false);
+    expect(flags[1]).toBe(false);
+    expect(flags[2]).toBe(false);
+    expect(flags[3]).toBe(true);
+    expect(flags[4]).toBe(true);
+  });
+});

package/src/grammar/facet.ts

@@ -0,0 +1,175 @@
+// ---------------------------------------------------------------------------
+// Faceting — split data into a grid of panels
+// ---------------------------------------------------------------------------
+// `chart.facet({ by })` produces one panel per unique value of `by`. Panels
+// are arranged in `ncol × nrow` (defaulting to a near-square grid) and share
+// scales by default. Each panel reuses the chart's geoms; only data and the
+// containing sub-frame change between panels.
+
+import { type Color, type Frame, type Layer, viewportFrame } from "insomni";
+import type { Aes } from "./aes.ts";
+import { resolveAes } from "./aes.ts";
+import type { Theme } from "./theme.ts";
+import {
+  DEFAULT_FACET_GAP,
+  DEFAULT_FACET_STRIP_FONT_SIZE,
+  DEFAULT_FACET_STRIP_HEIGHT,
+} from "./constants.ts";
+
+export type FacetScales = "fixed" | "free";
+
+export interface FacetStripStyle {
+  height?: number;
+  fontSize?: number;
+  color?: Color;
+  background?: Color;
+}
+
+export interface FacetSpec<T> {
+  /** Accessor / column name producing the facet key per datum. */
+  by: Aes<T, unknown>;
+  /** Number of columns. Default: ceil(sqrt(n)). */
+  ncol?: number;
+  /** Number of rows. Default: ceil(n / ncol). */
+  nrow?: number;
+  /**
+   * Scale handling across panels.
+   * - `"fixed"` (default) — every panel shares the same x/y/color/… scales.
+   * - `"free"` — each panel computes its own scales from its data.
+   */
+  scales?: FacetScales;
+  /** Spacing between panels in pixels. Default `12`. */
+  gap?: number;
+  /** Strip header style. */
+  strip?: FacetStripStyle;
+  /** Optional formatter for the strip label. */
+  format?: (key: unknown) => string;
+}
+
+export interface FacetPanel<T> {
+  key: unknown;
+  rows: T[];
+  /** Index into the column-major grid. */
+  col: number;
+  row: number;
+  /** Sub-frame within the chart's plot frame. */
+  frame: Frame;
+  /** True for the leftmost column — render y-axis only here. */
+  isLeftCol: boolean;
+  /** True for the bottom row of *populated* panels — render x-axis only here. */
+  isBottomRow: boolean;
+}
+
+export interface FacetLayout<T> {
+  panels: FacetPanel<T>[];
+  ncol: number;
+  nrow: number;
+  stripHeight: number;
+}
+
+export function groupForFacet<T>(
+  spec: FacetSpec<T>,
+  data: readonly T[],
+): { key: unknown; rows: T[] }[] {
+  const aes = resolveAes<T, unknown>(spec.by);
+  const keyOrder: unknown[] = [];
+  const buckets = new Map<unknown, T[]>();
+  for (let i = 0; i < data.length; i++) {
+    const datum = data[i]!;
+    const k = aes.fn(datum, i);
+    let bucket = buckets.get(k);
+    if (!bucket) {
+      bucket = [];
+      buckets.set(k, bucket);
+      keyOrder.push(k);
+    }
+    bucket.push(datum);
+  }
+  return keyOrder.map((key) => ({ key, rows: buckets.get(key)! }));
+}
+
+/**
+ * Slice the chart's plot frame into a grid of panel sub-frames. Each sub-frame
+ * contains a strip header at the top and a panel body underneath.
+ */
+export function computeFacetLayout<T>(
+  spec: FacetSpec<T>,
+  groups: readonly { key: unknown; rows: T[] }[],
+  plot: Frame,
+): FacetLayout<T> {
+  const n = groups.length;
+  const ncol = Math.max(1, spec.ncol ?? Math.ceil(Math.sqrt(n)));
+  const nrow = Math.max(1, spec.nrow ?? Math.ceil(n / ncol));
+  const gap = spec.gap ?? DEFAULT_FACET_GAP;
+  const stripHeight = spec.strip?.height ?? DEFAULT_FACET_STRIP_HEIGHT;
+
+  const panelWidth = (plot.width - gap * (ncol - 1)) / ncol;
+  const panelHeight = (plot.height - gap * (nrow - 1)) / nrow;
+
+  const panels: FacetPanel<T>[] = [];
+  // Determine the bottom-row index per column — for an n that doesn't fill
+  // the last row, panels in earlier columns still need x-axes drawn.
+  const colMaxRow = Array.from({ length: ncol }, () => -1);
+  for (let i = 0; i < n; i++) {
+    const col = i % ncol;
+    const row = Math.floor(i / ncol);
+    if (row > colMaxRow[col]!) colMaxRow[col] = row;
+  }
+
+  for (let i = 0; i < n; i++) {
+    const col = i % ncol;
+    const row = Math.floor(i / ncol);
+    const x = plot.x + col * (panelWidth + gap);
+    const y = plot.y + row * (panelHeight + gap) + stripHeight;
+    const frame = viewportFrame(panelWidth, Math.max(0, panelHeight - stripHeight)).translated(
+      x,
+      y,
+    );
+    panels.push({
+      key: groups[i]!.key,
+      rows: groups[i]!.rows,
+      col,
+      row,
+      frame,
+      isLeftCol: col === 0,
+      isBottomRow: row === colMaxRow[col]!,
+    });
+  }
+
+  return { panels, ncol, nrow, stripHeight };
+}
+
+/** Draw a strip header above a panel frame. */
+export function renderFacetStrip(
+  layer: Layer,
+  panel: FacetPanel<unknown>,
+  spec: FacetSpec<unknown>,
+  theme: Theme,
+): void {
+  const stripHeight = spec.strip?.height ?? DEFAULT_FACET_STRIP_HEIGHT;
+  const fontSize = spec.strip?.fontSize ?? DEFAULT_FACET_STRIP_FONT_SIZE;
+  const color = spec.strip?.color ?? theme.text.color;
+  const bg = spec.strip?.background;
+  const text = spec.format ? spec.format(panel.key) : String(panel.key);
+  const x = panel.frame.x;
+  const y = panel.frame.y - stripHeight;
+
+  if (bg) {
+    layer.pushRect({
+      x,
+      y,
+      width: panel.frame.width,
+      height: stripHeight,
+      fill: bg,
+    });
+  }
+  layer.pushText({
+    simple: true,
+    text,
+    x: x + panel.frame.width / 2,
+    y: y + (stripHeight - fontSize) / 2,
+    fontSize,
+    color,
+    align: "center",
+  });
+}

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

@@ -0,0 +1,94 @@
+import type { Color } from "insomni";
+import type { Aes } from "../aes.ts";
+import { type ResolvedAes } from "../aes.ts";
+import { type BandScale, type ContinuousScale, type GroupedBandScale } from "../../scales.ts";
+import type { MarkBuilder } from "../../marks.ts";
+import type { CompileContext } from "./types.ts";
+/** Default inner-band padding for dodged categorical layouts (fraction of band). */
+export declare const DEFAULT_GROUP_PADDING = 0.05;
+export interface CategoricalChannels<T> {
+    x: Aes<T, string | number | Date>;
+    y: Aes<T, number>;
+    color?: Aes<T, unknown>;
+}
+export interface CategoricalLayoutOptions {
+    /** Force orientation; defaults to detecting which axis is `band`. */
+    orientation?: "x" | "y";
+    /** Inner-band padding for grouped (color-split) layout. Default `0.05`. */
+    groupPadding?: number;
+    /** Fallback fill (used when there's no color channel). */
+    fill?: Color;
+}
+export interface CategoricalBucket {
+    /** Stringified category key (band-axis value). */
+    category: string;
+    /** Stringified inner-group key — undefined when not dodging. */
+    groupKey: string | undefined;
+    /** Numeric samples in this bucket, in input order. */
+    values: number[];
+}
+export interface CategoricalLayout {
+    orientation: "x" | "y";
+    bandAxis: BandScale<string>;
+    valueAxis: ContinuousScale;
+    /** Present when a color channel splits the band into sub-bands. */
+    inner: GroupedBandScale<string, string> | undefined;
+    /** Color column != band column (and color column is set). */
+    dodging: boolean;
+    /** Step on the band axis: inner bandwidth if dodging, else outer bandwidth. */
+    cellSize: number;
+    /** Buckets in first-encounter order. */
+    buckets: CategoricalBucket[];
+    /** Resolved fill (theme alpha already applied) for a bucket. */
+    resolveFill(bucket: CategoricalBucket): Color;
+    /** Plot-frame origin; cached to avoid `ctx.plot.topLeft` re-reads. */
+    ox: number;
+    oy: number;
+}
+export declare function prepareCategoricalLayout<T>(ctx: CompileContext<T>, channels: CategoricalChannels<T>, options?: CategoricalLayoutOptions): CategoricalLayout;
+/**
+ * Position of the band-axis center for a bucket. Returns `NaN` when the
+ * category isn't on the scale (caller should skip the bucket).
+ */
+export declare function bucketBandCenter(layout: CategoricalLayout, bucket: CategoricalBucket): number;
+/**
+ * Stable per-bucket seed for jitter / random offsets. Same bucket always
+ * yields the same value so re-renders don't dance.
+ */
+export declare function bucketSeed(bucket: CategoricalBucket, baseSeed: number): number;
+/**
+ * Aggregating geoms (boxplot / violin / histogram / ridgeline) emit one hit
+ * per bucket — not per source row — so their `compileHitTest` can't expose
+ * the user's column accessors meaningfully. Instead they `synthAes` channel
+ * accessors that ignore their datum and return a precomputed per-bucket
+ * value keyed by the hit's `dataIndex`. The `column` string flows through
+ * to the tooltip's row label.
+ */
+export declare function synthAes<T>(column: string, fn: (datum: T, index: number) => unknown): ResolvedAes<T, unknown>;
+export interface CountsLabelOptions {
+    /** Pixel offset from the band-axis edge of the plot frame. */
+    offset: number;
+    fontSize: number;
+    color: Color;
+    /** "Sample size" prefix. Default `"n="`. */
+    prefix?: string;
+    /**
+     * Where to anchor the labels:
+     *
+     * - `"outside"` (default) — outside the plot frame on the band-axis
+     *   perpendicular. Used by boxplot / violin so labels never collide with
+     *   the marks.
+     * - `"inline"` — at the band-axis center, inside the plot frame at the
+     *   row baseline (offset by `offset` along the value axis). Used by
+     *   ridgeline-style row charts where each row owns its baseline.
+     */
+    anchor?: "outside" | "inline";
+}
+/**
+ * Build a `MarkBuilder` that draws `n=<count>` labels for each band-axis
+ * category, just outside the plot frame on the band-axis perpendicular.
+ *
+ * Counts are summed across dodge groups so a band with `A: 10` and
+ * `B: 15` displays `n=25`.
+ */
+export declare function countsLabelMark(layout: CategoricalLayout, options: CountsLabelOptions, plotWidth: number, plotHeight: number): MarkBuilder;

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

@@ -0,0 +1,52 @@
+import { type BoxStats, type BoxStatsOptions, type KdeOptions, type KdeResult } from "../../stats/index.ts";
+import type { CategoricalBucket } from "./_categorical.ts";
+/**
+ * Compute the value-axis extent across all buckets' KDEs. Used by `violin`
+ * and `ridgeline` to extend their value-axis domain so smoothed tails don't
+ * render past the plot frame. Returns `null` when no bucket yields a usable
+ * KDE (empty input, or all values non-finite).
+ */
+export declare function kdeValueExtent(buckets: Iterable<readonly number[]>, options: KdeOptions): readonly [number, number] | null;
+/** How per-row width relates to density across groups. */
+export type DensityScale = "width" | "area" | "count";
+export interface GroupedKdeResult {
+    bucket: CategoricalBucket;
+    /** KDE evaluated on a fixed grid (`null` only when bucket has no finite values). */
+    kde: KdeResult;
+    /** Max raw density on the KDE grid, before any normalization. */
+    maxDensity: number;
+    /** Sample size that produced the KDE. */
+    n: number;
+    /** Box stats for the same sample — used by inner annotations. */
+    stats: BoxStats;
+}
+export interface ComputeGroupedKdeOptions {
+    kde: KdeOptions;
+    box: BoxStatsOptions;
+    /**
+     * Width-scaling mode. Affects only `globalMaxDensity`, which is then folded
+     * into `densityWidthFn`. The per-bucket `maxDensity` stays raw so callers
+     * that need it (e.g. for `width` mode) get an unscaled reference.
+     */
+    scale: DensityScale;
+}
+/**
+ * Compute a KDE + box stats for each bucket. Buckets that yield no usable KDE
+ * (zero finite samples) are dropped from the output. Returns the global max
+ * density used for cross-group `area` / `count` normalization.
+ */
+export declare function computeGroupedKde(buckets: readonly CategoricalBucket[], options: ComputeGroupedKdeOptions): {
+    groups: GroupedKdeResult[];
+    globalMaxDensity: number;
+};
+/**
+ * Build the `density → pixel width` mapping for one group, given the global
+ * max density (for `area` / `count` modes) and the slot half-width in pixels.
+ *
+ * - `"width"` — each group fills its slot. Densities are not comparable.
+ * - `"area"` — each group is normalized by the global max density. Areas
+ *   are comparable across groups.
+ * - `"count"` — like area, but multiplied by `n` so groups with more samples
+ *   render larger.
+ */
+export declare function densityWidthFn(group: GroupedKdeResult, globalMaxDensity: number, scale: DensityScale, halfWidth: number): (density: number) => number;

package/src/grammar/geoms/_distribution.ts

@@ -0,0 +1,125 @@
+// ---------------------------------------------------------------------------
+// Per-group distribution helpers
+// ---------------------------------------------------------------------------
+// Pure (no render deps) helpers shared between distribution geoms — violin and
+// ridgeline. Centralizes:
+//   - per-bucket KDE evaluation
+//   - per-bucket box stats (used for inner annotations)
+//   - cross-group max-density bookkeeping for `area` / `count` width modes
+//   - the width-from-density function each geom plugs into its layout
+
+import {
+  boxStats,
+  kde,
+  type BoxStats,
+  type BoxStatsOptions,
+  type KdeOptions,
+  type KdeResult,
+} from "../../stats/index.ts";
+import type { CategoricalBucket } from "./_categorical.ts";
+
+/**
+ * Compute the value-axis extent across all buckets' KDEs. Used by `violin`
+ * and `ridgeline` to extend their value-axis domain so smoothed tails don't
+ * render past the plot frame. Returns `null` when no bucket yields a usable
+ * KDE (empty input, or all values non-finite).
+ */
+export function kdeValueExtent(
+  buckets: Iterable<readonly number[]>,
+  options: KdeOptions,
+): readonly [number, number] | null {
+  let lo = Number.POSITIVE_INFINITY;
+  let hi = Number.NEGATIVE_INFINITY;
+  for (const values of buckets) {
+    const k = kde(values, options);
+    if (!k || k.x.length === 0) continue;
+    const x0 = k.x[0]!;
+    const xn = k.x[k.x.length - 1]!;
+    if (x0 < lo) lo = x0;
+    if (xn > hi) hi = xn;
+  }
+  if (!Number.isFinite(lo) || !Number.isFinite(hi)) return null;
+  return [lo, hi];
+}
+
+/** How per-row width relates to density across groups. */
+export type DensityScale = "width" | "area" | "count";
+
+export interface GroupedKdeResult {
+  bucket: CategoricalBucket;
+  /** KDE evaluated on a fixed grid (`null` only when bucket has no finite values). */
+  kde: KdeResult;
+  /** Max raw density on the KDE grid, before any normalization. */
+  maxDensity: number;
+  /** Sample size that produced the KDE. */
+  n: number;
+  /** Box stats for the same sample — used by inner annotations. */
+  stats: BoxStats;
+}
+
+export interface ComputeGroupedKdeOptions {
+  kde: KdeOptions;
+  box: BoxStatsOptions;
+  /**
+   * Width-scaling mode. Affects only `globalMaxDensity`, which is then folded
+   * into `densityWidthFn`. The per-bucket `maxDensity` stays raw so callers
+   * that need it (e.g. for `width` mode) get an unscaled reference.
+   */
+  scale: DensityScale;
+}
+
+/**
+ * Compute a KDE + box stats for each bucket. Buckets that yield no usable KDE
+ * (zero finite samples) are dropped from the output. Returns the global max
+ * density used for cross-group `area` / `count` normalization.
+ */
+export function computeGroupedKde(
+  buckets: readonly CategoricalBucket[],
+  options: ComputeGroupedKdeOptions,
+): { groups: GroupedKdeResult[]; globalMaxDensity: number } {
+  const groups: GroupedKdeResult[] = [];
+  let globalMaxDensity = 0;
+  for (const bucket of buckets) {
+    const k = kde(bucket.values, options.kde);
+    if (!k) continue;
+    const stats = boxStats(bucket.values, options.box);
+    if (!stats) continue;
+    let max = 0;
+    for (const v of k.y) if (v > max) max = v;
+    const scaledMax = options.scale === "count" ? max * stats.n : max;
+    if (scaledMax > globalMaxDensity) globalMaxDensity = scaledMax;
+    groups.push({ bucket, kde: k, maxDensity: max, n: stats.n, stats });
+  }
+  return { groups, globalMaxDensity };
+}
+
+/**
+ * Build the `density → pixel width` mapping for one group, given the global
+ * max density (for `area` / `count` modes) and the slot half-width in pixels.
+ *
+ * - `"width"` — each group fills its slot. Densities are not comparable.
+ * - `"area"` — each group is normalized by the global max density. Areas
+ *   are comparable across groups.
+ * - `"count"` — like area, but multiplied by `n` so groups with more samples
+ *   render larger.
+ */
+export function densityWidthFn(
+  group: GroupedKdeResult,
+  globalMaxDensity: number,
+  scale: DensityScale,
+  halfWidth: number,
+): (density: number) => number {
+  if (scale === "width") {
+    if (group.maxDensity <= 0) return () => 0;
+    const k = halfWidth / group.maxDensity;
+    return (d) => d * k;
+  }
+  const ref = globalMaxDensity > 0 ? globalMaxDensity : 1;
+  if (scale === "count") {
+    const k = (halfWidth * group.n) / ref;
+    return (d) => d * k;
+  }
+  // area
+  const k = halfWidth / ref;
+  return (d) => d * k;
+}

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

@@ -0,0 +1,69 @@
+import type { Color, Layer } from "insomni";
+import type { MarkBuilder, MarkOrigin } from "../../marks.ts";
+import { type Coord } from "../coord.ts";
+import type { Theme } from "../theme.ts";
+import type { CompileContext, GeomKind } from "./types.ts";
+/**
+ * Resolve `ctx.coord` to a concrete {@link Coord}. The interface flags `coord`
+ * as optional in {@link CompileContext} during the Phase 1 migration to the
+ * `Coord` API — geoms call this once at the top of their compile path to get
+ * a non-null projection, falling back to {@link coordCartesian} when the
+ * pipeline didn't supply one (e.g. legacy direct-compile call sites). Under
+ * Cartesian both `project` and `segment` are the identity, so this is a
+ * zero-pixel-diff drop-in for every existing geom.
+ */
+export declare function resolveCoord<T>(ctx: CompileContext<T>): Coord;
+/**
+ * Default alpha applied to non-selected marks while a selection is active.
+ * Lifted into a constant so geoms stay consistent without each importing the
+ * theme's selection config; per-mount overrides happen via the selection
+ * config (see chart.ts:SelectionConfig.dimAlpha).
+ */
+export declare const SELECTION_DIM_ALPHA = 0.3;
+/**
+ * Returns the set of selected `dataIndex`es that belong to *this* geom (kind
+ * matches and the data array reference matches), or `null` when no selection
+ * row matches. Geoms use this to push stroke rings on the matching rows.
+ */
+export declare function selectedIndicesFor<T>(ctx: CompileContext<T>, kind: GeomKind): Set<number> | null;
+/** True when any selection is active anywhere in the chart. */
+export declare function selectionActive<T>(ctx: CompileContext<T>): boolean;
+/**
+ * Multi-series equivalent of {@link selectedIndicesFor}: returns the list of
+ * `(dataIndex, seriesKey)` pairs selected for *this* geom. Used by stacked /
+ * dodged geoms where a single source row produces multiple visible segments
+ * and the ring must distinguish them by series key.
+ */
+export declare function selectedSegmentsFor<T>(ctx: CompileContext<T>, kind: GeomKind): Array<{
+    dataIndex: number;
+    seriesKey?: string;
+}> | null;
+/**
+ * Wrap a `MarkBuilder` so it composes into the `compile()` builder list with
+ * a fixed origin (typically the plot frame's top-left). Geoms collect these
+ * into the array returned from `compile`. Pass `length` to override the
+ * builder's reported length — used for label sub-marks where the visual
+ * count differs from the underlying mark's vertex count.
+ */
+export declare function wrapMark(mark: MarkBuilder, origin: MarkOrigin, length?: number): {
+    length: number;
+    addTo: (layer: Layer) => Layer;
+};
+/**
+ * Build a `MarkBuilder` from a draw callback. Used for one-off shapes that
+ * don't fit a mark factory — currently the hover-highlight halo each geom
+ * pushes for `ctx.hovered`. Coordinates passed to `draw` are layer-local
+ * (the caller has already applied any plot-frame offset).
+ */
+export declare function inlineMark(draw: (layer: Layer) => void, length?: number): MarkBuilder;
+export declare function resolveFillAlpha(selected: boolean, theme: Theme): number;
+export declare function defaultMarkFill(theme: Theme): Color;
+export declare function selectChannels<X, Y>(orientation: "x" | "y", channels: {
+    x: X;
+    y: Y;
+}): {
+    categoryChannel: X | Y;
+    valueChannel: X | Y;
+};
+/** Highlight ring used by point/line/area on `ctx.hovered`. */
+export declare function haloRing(layer: Layer, cx: number, cy: number, radius: number, color: Color, width?: number): void;