insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/_mark.ts

@@ -0,0 +1,136 @@
+// ---------------------------------------------------------------------------
+// Geom compile helpers
+// ---------------------------------------------------------------------------
+
+import type { Color, Layer } from "insomni";
+import type { MarkBuilder, MarkOrigin } from "../../marks.ts";
+import { coordCartesian, type Coord } from "../coord.ts";
+import type { Theme } from "../theme.ts";
+import type { CompileContext, GeomKind, HoveredHit } 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 function resolveCoord<T>(ctx: CompileContext<T>): Coord {
+  return ctx.coord ?? coordCartesian();
+}
+
+/**
+ * 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 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 function selectedIndicesFor<T>(ctx: CompileContext<T>, kind: GeomKind): Set<number> | null {
+  const sel = ctx.selected;
+  if (!sel || sel.length === 0) return null;
+  const data = ctx.data as readonly unknown[];
+  const out = new Set<number>();
+  for (const h of sel as readonly HoveredHit[]) {
+    if (h.geomKind === kind && h.data === data) out.add(h.dataIndex);
+  }
+  return out.size > 0 ? out : null;
+}
+
+/** True when any selection is active anywhere in the chart. */
+export function selectionActive<T>(ctx: CompileContext<T>): boolean {
+  return !!ctx.selected && ctx.selected.length > 0;
+}
+
+/**
+ * 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 function selectedSegmentsFor<T>(
+  ctx: CompileContext<T>,
+  kind: GeomKind,
+): Array<{ dataIndex: number; seriesKey?: string }> | null {
+  const sel = ctx.selected;
+  if (!sel || sel.length === 0) return null;
+  const data = ctx.data as readonly unknown[];
+  const out: Array<{ dataIndex: number; seriesKey?: string }> = [];
+  for (const h of sel as readonly HoveredHit[]) {
+    if (h.geomKind === kind && h.data === data) {
+      out.push({ dataIndex: h.dataIndex, seriesKey: h.seriesKey });
+    }
+  }
+  return out.length > 0 ? out : 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 function wrapMark(
+  mark: MarkBuilder,
+  origin: MarkOrigin,
+  length: number = mark.length,
+): { length: number; addTo: (layer: Layer) => Layer } {
+  return {
+    length,
+    addTo: (layer: Layer) => mark.addTo(layer, origin),
+  };
+}
+
+/**
+ * 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 function inlineMark(draw: (layer: Layer) => void, length: number = 1): MarkBuilder {
+  return {
+    length,
+    addTo(layer: Layer) {
+      draw(layer);
+      return layer;
+    },
+  };
+}
+
+export function resolveFillAlpha(selected: boolean, theme: Theme): number {
+  return selected ? theme.marks.fillAlpha * SELECTION_DIM_ALPHA : theme.marks.fillAlpha;
+}
+
+export function defaultMarkFill(theme: Theme): Color {
+  return theme.palettes.categorical(0);
+}
+
+export function selectChannels<X, Y>(
+  orientation: "x" | "y",
+  channels: { x: X; y: Y },
+): { categoryChannel: X | Y; valueChannel: X | Y } {
+  return orientation === "y"
+    ? { categoryChannel: channels.x, valueChannel: channels.y }
+    : { categoryChannel: channels.y, valueChannel: channels.x };
+}
+
+/** Highlight ring used by point/line/area on `ctx.hovered`. */
+export function haloRing(
+  layer: Layer,
+  cx: number,
+  cy: number,
+  radius: number,
+  color: Color,
+  width: number = 2,
+): void {
+  layer.pushCircle({ cx, cy, radius, stroke: color, strokeWidth: width });
+}

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

@@ -0,0 +1,41 @@
+import type { Color, Layer } from "insomni";
+import type { MarkOrigin } from "../../marks.ts";
+/**
+ * Halo rect to be painted on top of a geom's main fills, so the active
+ * hover row's outline isn't occluded by adjacent cells. `color` is per-halo
+ * so multi-series geoms (histogram) can use per-cell highlight colors while
+ * single-series geoms (tile) just thread one color through every entry.
+ */
+export interface Halo {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    color: Color;
+}
+/**
+ * Push every halo rect as a stroke-only outline on top of `layer`. Caller
+ * supplies the shared stroke width (typically `emphasis.haloStrokeWidth`)
+ * and an optional corner radius matching the underlying fills.
+ */
+export declare function paintHalos(layer: Layer, halos: readonly Halo[], options: {
+    strokeWidth: number;
+    cornerRadius?: number;
+}): void;
+/**
+ * Orientation-aware bar bbox: takes the band-axis start + bandwidth and the
+ * value-axis pixel + baseline, returns the axis-aligned rect in mark-local
+ * coordinates (pre-translated by `origin`).
+ *
+ * `orientation === "y"` means categories on the x-axis (vertical bars rising
+ * along y); `"x"` means categories on the y-axis (horizontal bars).
+ *
+ * Returns `null` when either input pixel isn't finite — callers should
+ * `continue` on null so NaN bands don't produce zero-area garbage rects.
+ */
+export declare function barRect(orientation: "x" | "y", bandStart: number, bandwidth: number, valuePx: number, baseline: number, origin: MarkOrigin): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;

package/src/grammar/geoms/_shape.ts

@@ -0,0 +1,74 @@
+// ---------------------------------------------------------------------------
+// Shape-geom helpers — orientation-aware rect math + halo painting
+// ---------------------------------------------------------------------------
+// Shared by bar / histogram / tile. These geoms all compute axis-aligned
+// rects from a band+value+baseline triple and overlay halo rings on the
+// active hover row. The bbox math and the halo paint loop were copy-pasted
+// across files; this module owns both.
+
+import type { Color, Layer } from "insomni";
+import type { MarkOrigin } from "../../marks.ts";
+
+/**
+ * Halo rect to be painted on top of a geom's main fills, so the active
+ * hover row's outline isn't occluded by adjacent cells. `color` is per-halo
+ * so multi-series geoms (histogram) can use per-cell highlight colors while
+ * single-series geoms (tile) just thread one color through every entry.
+ */
+export interface Halo {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  color: Color;
+}
+
+/**
+ * Push every halo rect as a stroke-only outline on top of `layer`. Caller
+ * supplies the shared stroke width (typically `emphasis.haloStrokeWidth`)
+ * and an optional corner radius matching the underlying fills.
+ */
+export function paintHalos(
+  layer: Layer,
+  halos: readonly Halo[],
+  options: { strokeWidth: number; cornerRadius?: number },
+): void {
+  for (const halo of halos) {
+    layer.pushRect({
+      x: halo.x,
+      y: halo.y,
+      width: halo.w,
+      height: halo.h,
+      cornerRadius: options.cornerRadius,
+      stroke: halo.color,
+      strokeWidth: options.strokeWidth,
+    });
+  }
+}
+
+/**
+ * Orientation-aware bar bbox: takes the band-axis start + bandwidth and the
+ * value-axis pixel + baseline, returns the axis-aligned rect in mark-local
+ * coordinates (pre-translated by `origin`).
+ *
+ * `orientation === "y"` means categories on the x-axis (vertical bars rising
+ * along y); `"x"` means categories on the y-axis (horizontal bars).
+ *
+ * Returns `null` when either input pixel isn't finite — callers should
+ * `continue` on null so NaN bands don't produce zero-area garbage rects.
+ */
+export function barRect(
+  orientation: "x" | "y",
+  bandStart: number,
+  bandwidth: number,
+  valuePx: number,
+  baseline: number,
+  origin: MarkOrigin,
+): { x: number; y: number; width: number; height: number } | null {
+  if (!Number.isFinite(bandStart) || !Number.isFinite(valuePx)) return null;
+  const x = (origin.x ?? 0) + (orientation === "y" ? bandStart : Math.min(baseline, valuePx));
+  const y = (origin.y ?? 0) + (orientation === "y" ? Math.min(baseline, valuePx) : bandStart);
+  const width = orientation === "y" ? bandwidth : Math.abs(valuePx - baseline);
+  const height = orientation === "y" ? Math.abs(valuePx - baseline) : bandwidth;
+  return { x, y, width, height };
+}

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

@@ -0,0 +1,95 @@
+import { type Color } from "insomni";
+import { type LineCurve, type PointShapeKind } from "../../marks.ts";
+import type { Aes } from "../aes.ts";
+import type { Geom } from "./types.ts";
+export type AggregateBinBy = "x" | "y";
+export type AggregateBinSize = number | "auto" | ((info: AutoBinSizeInfo) => number);
+export interface AutoBinSizeInfo {
+    /** Pixel span of the binned axis (positive). */
+    pixelSpan: number;
+    /** Domain span of the binned axis in axis units (positive). For time scales, ms. */
+    domainSpan: number;
+    /** `pixelSpan / domainSpan` — pixels per domain unit on the binned axis. */
+    pixelsPerUnit: number;
+}
+export type AggregateSummaryKind = "mean" | "median" | "count" | "sum" | "first" | "last";
+export interface AggregateBinView<T> {
+    /** Values from the *non-binned* axis, in input order within this bin. */
+    values: readonly number[];
+    /** Source items inside this bin, in input order. */
+    items: readonly T[];
+    /** Count after filter. */
+    count: number;
+    /** Bin's lower edge on the binned axis (inclusive). */
+    lo: number;
+    /** Bin's upper edge on the binned axis (exclusive, except the final bin). */
+    hi: number;
+}
+export type AggregateSummary<T> = AggregateSummaryKind | ((bin: AggregateBinView<T>) => number);
+/** Result of a bundle summary — one center + a [lo, hi] range per bin. */
+export interface AggregateBundleResult {
+    center: number;
+    lo: number;
+    hi: number;
+}
+export type AggregateBundleSummaryKind = "mean+ci" | "median+iqr";
+/**
+ * Bundle summaries emit `{ center, lo, hi }` per bin and pair with the
+ * `interval` or `ribbon` inner geom. Built-in kinds plus a quantile triple
+ * `{ quantiles: [loQ, centerQ, hiQ] }` (e.g. `[0.1, 0.5, 0.9]` for an 80%
+ * range) or a custom function returning the bundle directly.
+ */
+export type AggregateBundleSummary<T> = AggregateBundleSummaryKind | {
+    quantiles: readonly [number, number, number];
+} | ((bin: AggregateBinView<T>) => AggregateBundleResult);
+export interface AggregateChannels<T> {
+    x: Aes<T, number | Date>;
+    y: Aes<T, number | Date>;
+}
+export type AggregateInnerGeom = "point" | "line" | "bar" | "interval" | "ribbon";
+export interface AggregateOptions<T> {
+    /** Axis to slide along. Default `"x"`. */
+    binBy?: AggregateBinBy;
+    /** Bin width in domain units; `"auto"` targets `~autoTargetPx` px. Default `"auto"`. */
+    binSize?: AggregateBinSize;
+    /**
+     * Reduction applied per bin. Scalar kinds (`"mean"`, `"median"`, …) pair
+     * with `geom: "point" | "line" | "bar"`. Bundle kinds (`"mean+ci"`,
+     * `"median+iqr"`, `{ quantiles }`, function-returning-`{center, lo, hi}`)
+     * pair with `geom: "interval" | "ribbon"`. Default `"mean"`.
+     */
+    summary?: AggregateSummary<T> | AggregateBundleSummary<T>;
+    /** Row predicate. Rejected rows are excluded from both binning and the
+     *  raw-fallback path. */
+    filter?: (datum: T, index: number) => boolean;
+    /** When `avg-points-per-bin < dissolveAt`, render raw geom instead.
+     *  Default `1.2`. */
+    dissolveAt?: number;
+    /** Inner mark kind. Default `"point"`. */
+    geom?: AggregateInnerGeom;
+    /** Fill / stroke applied to every emitted mark. */
+    fill?: Color;
+    stroke?: Color;
+    strokeWidth?: number;
+    /** Point-specific. */
+    radius?: number;
+    shape?: PointShapeKind;
+    /** Line-specific. */
+    curve?: LineCurve;
+    /** Target pixels per bin for `"auto"` sizing. Default `7`. */
+    autoTargetPx?: number;
+    /** Display label for legend / hit-test (forwarded to inner mark). */
+    label?: string;
+    /**
+     * Confidence level for the `"mean+ci"` bundle summary. Default `0.95`.
+     * Ignored for other summaries.
+     */
+    ciLevel?: number;
+    /** Interval-specific: render perpendicular caps. Default `true`. */
+    caps?: boolean;
+    /** Interval-specific: cap length in pixels. Default `6`. */
+    capWidth?: number;
+    /** Ribbon-specific: fill alpha override (otherwise theme.marks.ribbonFillAlpha). */
+    fillAlpha?: number;
+}
+export declare function aggregate<T>(channels: AggregateChannels<T>, options?: AggregateOptions<T>): Geom<T>;