insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/area.ts

@@ -0,0 +1,578 @@
+// ---------------------------------------------------------------------------
+// area geom
+// ---------------------------------------------------------------------------
+
+import { lerpColor, type Color, type Layer, type Vec2 } from "insomni";
+import {
+  areaMark,
+  pushFilledPolygon,
+  stackedAreaMark,
+  type MarkBuilder,
+  type StackOffset,
+  type StackOrder,
+} from "../../marks.ts";
+import { stack } from "../../marks/stack.ts";
+import type { ContinuousScale } from "../../scales.ts";
+import type { Aes } from "../aes.ts";
+import { resolveAes } from "../aes.ts";
+import { alphaize, seriesColor } from "../color-utils.ts";
+import { areaSwatch } from "../../legend.ts";
+import {
+  haloRing,
+  inlineMark,
+  defaultMarkFill,
+  resolveCoord,
+  resolveFillAlpha,
+  SELECTION_DIM_ALPHA,
+  selectedIndicesFor,
+  selectedSegmentsFor,
+  selectionActive,
+  wrapMark,
+} from "./_mark.ts";
+import type {
+  CompileContext,
+  CompiledHitTest,
+  Geom,
+  GeomFrame,
+  ResolvedChannelMap,
+  ScaleHints,
+} from "./types.ts";
+
+export type AreaPosition = "identity" | "stack" | "fill";
+
+export interface AreaChannels<T> {
+  x: Aes<T, number | Date>;
+  /**
+   * Single column → simple area from y=0 to y. Array of column keys → stacked
+   * area, with the implicit `__series` color channel keyed by column name.
+   */
+  y: Aes<T, number | Date> | readonly (keyof T & string)[];
+  color?: Aes<T, unknown>;
+}
+
+export interface AreaOptions {
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** "identity" (default), "stack" (offset zero), or "fill" (offset expand). */
+  position?: AreaPosition;
+  /** Stack ordering — only meaningful with stacked positions. */
+  order?: StackOrder;
+  label?: string;
+  /**
+   * When true, hover hit-tests resolve to the nearest vertex *by x* — the
+   * cursor's vertical position doesn't influence which datum (or stacked
+   * segment) is picked, so the user can hover anywhere along the area.
+   * Default `false` (per-vertex Euclidean pick within `pickRadius`).
+   */
+  nearestX?: boolean;
+}
+
+export function area<T>(channels: AreaChannels<T>, options: AreaOptions = {}): Geom<T> {
+  const isStacked = Array.isArray(channels.y);
+  // Area baselines at 0 on y. For `fill` (expand offset) the rendered range
+  // is [0, 1] regardless of input totals, so set an explicit domain.
+  const scaleHints: ScaleHints = isStacked
+    ? options.position === "fill"
+      ? { y: { domain: [0, 1] } }
+      : { y: { includeZero: true } }
+    : { y: { includeZero: true } };
+  return {
+    kind: "area",
+    channels: { x: channels.x, y: channels.y, color: channels.color },
+    label: options.label,
+    scaleHints,
+    legendSwatch: (color) => areaSwatch({ fill: color, width: 14, height: 10 }),
+    compile(ctx: CompileContext<T>) {
+      const { data, scales, plot, theme } = ctx;
+      const coord = resolveCoord(ctx);
+      const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+      const xFn = scales.x.fn;
+
+      const fill = options.fill ?? defaultMarkFill(theme);
+      const stroke = options.stroke;
+      const strokeWidth = options.strokeWidth;
+      const rowKey = (d: T, i: number) => (ctx.transitionKey ? ctx.transitionKey(d, i) : String(i));
+
+      if (!isStacked) {
+        const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+        const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+        const isHidden = (d: T, i: number) => {
+          if (!ctx.hidden || !colorAes) return false;
+          return ctx.hidden.has(String(colorAes.fn(d, i)));
+        };
+
+        const yScale = scales.y.fn;
+        const yBaseline = yScale(0);
+        const anim = ctx.activeTransition;
+        const fromIndexFor = (d: T, i: number) => anim?.matchIndex(rowKey(d, i), i);
+        // Dim simple-area fill when a selection is active anywhere in the
+        // chart and no row of this area is selected. Stacked areas do their
+        // own per-segment dimming via `dimMulti` below.
+        const selectedSetSimple = selectedIndicesFor(ctx, "area");
+        const dimSimple = selectionActive(ctx) && selectedSetSimple === null;
+        const fillAlphaResolved = resolveFillAlpha(dimSimple, theme);
+        const resolvedFill = alphaize(fill, fillAlphaResolved);
+
+        // Lerp fill color if animating.
+        const animFill: Color = anim
+          ? (() => {
+              // Use datum 0's stored color as representative for the whole area fill.
+              if (anim.from.count === 0) return resolvedFill;
+              const fromFill: Color = {
+                r: anim.from.rgba[0]!,
+                g: anim.from.rgba[1]!,
+                b: anim.from.rgba[2]!,
+                a: anim.from.rgba[3]!,
+              };
+              return lerpColor(fromFill, resolvedFill, anim.t);
+            })()
+          : resolvedFill;
+
+        // Compute the per-datum plot-frame x, y0, y1 (with animation lerp),
+        // then project each edge vertex through the active coord. Under
+        // `coordCartesian()` projection is the identity; polar (Phase 3)
+        // will project the top edge and baseline as separate vertex streams.
+        const computeFrame = (
+          d: T,
+          i: number,
+        ): { x: number; y0: number; y1: number; hidden: boolean } => {
+          if (isHidden(d, i)) return { x: NaN, y0: NaN, y1: NaN, hidden: true };
+          const toX = xFn(xAes.fn(d, i));
+          const toY1 = yScale(yAes.fn(d, i));
+          const fromIndex = fromIndexFor(d, i);
+          let px = toX;
+          let py1 = toY1;
+          let py0 = yBaseline;
+          if (anim && fromIndex !== undefined) {
+            if (Number.isFinite(anim.from.x[fromIndex]!)) {
+              px = anim.from.x[fromIndex]! + (toX - anim.from.x[fromIndex]!) * anim.t;
+            }
+            if (Number.isFinite(anim.from.y[fromIndex]!)) {
+              py1 = anim.from.y[fromIndex]! + (toY1 - anim.from.y[fromIndex]!) * anim.t;
+            }
+            const fromR = anim.from.r?.[fromIndex];
+            if (fromR !== undefined && Number.isFinite(fromR)) {
+              py0 = fromR + (yBaseline - fromR) * anim.t;
+            }
+          }
+          return { x: px, y0: py0, y1: py1, hidden: false };
+        };
+        let builders: MarkBuilder[];
+        const isPolar = coord.kind === "polar";
+        if (isPolar) {
+          // Polar area: the area "baseline" (y0) should map to r=0 (the polar
+          // centre) at the data point's angle, rather than the Cartesian y=0
+          // baseline (which under angleChannel="y" gives a constant starting
+          // angle). We also tessellate the top edge through coord.segment so
+          // consecutive sector-tip vertices follow arcs instead of straight
+          // chords.
+          const xDomain = scales.x.axisScale.domain as [number, number];
+          const xBaselinePx = xFn(xDomain[0] ?? 0);
+          const tessTop: Vec2[] = [];
+          const tessBottom: Vec2[] = [];
+          const ox = plot.topLeft.x;
+          const oy = plot.topLeft.y;
+          for (let i = 0; i < data.length; i++) {
+            const d = data[i]!;
+            const f = computeFrame(d, i);
+            if (f.hidden) continue;
+            // Top vertex: full projection at (hours, sector).
+            const topP = coord.project({ x: f.x, y: f.y1 });
+            // Bottom vertex: at the origin angle (same sector) but r=0.
+            const botP = coord.project({ x: xBaselinePx, y: f.y1 });
+            // Tessellate the top edge segment from previous → current.
+            if (tessTop.length > 0) {
+              if (i > 0) {
+                const prev = computeFrame(data[i - 1]!, i - 1);
+                if (!prev.hidden) {
+                  const seg = coord.segment({ x: prev.x, y: prev.y1 }, { x: f.x, y: f.y1 });
+                  // Skip first (already pushed) and last (pushed as topP below).
+                  for (let k = 1; k < seg.length - 1; k++) {
+                    tessTop.push({ x: ox + seg[k]!.x, y: oy + seg[k]!.y });
+                  }
+                  // Bottom edge: tessellate from previous → current baseline.
+                  const botSeg = coord.segment(
+                    { x: xBaselinePx, y: prev.y1 },
+                    { x: xBaselinePx, y: f.y1 },
+                  );
+                  for (let k = 1; k < botSeg.length - 1; k++) {
+                    tessBottom.push({ x: ox + botSeg[k]!.x, y: oy + botSeg[k]!.y });
+                  }
+                }
+              }
+            }
+            tessTop.push({ x: ox + topP.x, y: oy + topP.y });
+            tessBottom.push({ x: ox + botP.x, y: oy + botP.y });
+          }
+          // Build the closed polygon: top edge forward → bottom edge reversed.
+          const points: Vec2[] = [...tessTop];
+          for (let i = tessBottom.length - 1; i >= 0; i--) {
+            points.push(tessBottom[i]!);
+          }
+          builders = [
+            {
+              length: data.length,
+              addTo(layer: Layer) {
+                pushFilledPolygon(layer, points, {
+                  fill: animFill,
+                  stroke: stroke && dimSimple ? alphaize(stroke, SELECTION_DIM_ALPHA) : stroke,
+                  strokeWidth,
+                });
+                return layer;
+              },
+            },
+          ];
+        } else {
+          const mark = areaMark(data, {
+            x: (d, i) => {
+              const f = computeFrame(d, i);
+              if (f.hidden) return NaN;
+              return coord.project({ x: f.x, y: f.y1 }).x;
+            },
+            y0: (d, i) => {
+              const f = computeFrame(d, i);
+              return coord.project({ x: f.x, y: f.y0 }).y;
+            },
+            y1: (d, i) => {
+              const f = computeFrame(d, i);
+              if (f.hidden) return NaN;
+              return coord.project({ x: f.x, y: f.y1 }).y;
+            },
+            fill: animFill,
+            stroke: stroke && dimSimple ? alphaize(stroke, SELECTION_DIM_ALPHA) : stroke,
+            strokeWidth,
+          });
+          builders = [wrapMark(mark, plot.topLeft, data.length)];
+        }
+
+        // Hover halo on the active top-edge vertex.
+        if (ctx.hovered && ctx.hovered.geomKind === "area" && ctx.hovered.data === data) {
+          const i = ctx.hovered.dataIndex;
+          const d = data[i];
+          if (d !== undefined) {
+            const xv = xAes.fn(d, i);
+            const yv = yAes.fn(d, i);
+            if (xv != null && yv != null) {
+              const rawX = xFn(xv);
+              const rawY = yScale(yv);
+              if (Number.isFinite(rawX) && Number.isFinite(rawY)) {
+                const projected = coord.project({ x: rawX, y: rawY });
+                const cx = plot.topLeft.x + projected.x;
+                const cy = plot.topLeft.y + projected.y;
+                builders.push(inlineMark((layer) => haloRing(layer, cx, cy, 6, fill, 2)));
+              }
+            }
+          }
+        }
+
+        // Selection rings — one per selected top-edge vertex.
+        const selectedSet = selectedIndicesFor(ctx, "area");
+        if (selectedSet) {
+          for (const i of selectedSet) {
+            const d = data[i];
+            if (d === undefined) continue;
+            const xv = xAes.fn(d, i);
+            const yv = yAes.fn(d, i);
+            if (xv == null || yv == null) continue;
+            const rawX = xFn(xv);
+            const rawY = yScale(yv);
+            if (!Number.isFinite(rawX) || !Number.isFinite(rawY)) continue;
+            const projected = coord.project({ x: rawX, y: rawY });
+            const cx = plot.topLeft.x + projected.x;
+            const cy = plot.topLeft.y + projected.y;
+            builders.push(inlineMark((layer) => haloRing(layer, cx, cy, 6, fill, 2)));
+          }
+        }
+
+        return builders;
+      }
+
+      // Stacked: y is keys[]; build a stackedAreaMark.
+      const keys = channels.y as readonly (keyof T & string)[];
+      // activeKeys excludes hidden series; color domain stays full-keys so
+      // visible series keep stable colors when siblings are toggled.
+      const activeKeys = ctx.hidden ? keys.filter((k) => !ctx.hidden!.has(k)) : keys;
+      const yContinuous = scales.y.axisScale as ContinuousScale;
+      const offset: StackOffset = options.position === "fill" ? "expand" : "zero";
+      const colorFn = seriesColor(scales.color, theme.palettes.categorical, [...keys] as string[]);
+      const anim = ctx.activeTransition;
+      const stackedSegments = stack(data, [...activeKeys] as string[], {
+        offset,
+        order: options.order,
+      });
+      // When a selection is active, dim the base stacked area uniformly and
+      // re-overlay the selected segments' top vertex at full color so they
+      // pop. Mirrors the multi-series bar treatment.
+      const dimMulti = !!ctx.selected && ctx.selected.length > 0;
+      const baseFillAlpha = resolveFillAlpha(dimMulti, theme);
+      const builders: MarkBuilder[] = [];
+      if (anim) {
+        const segments = stackedSegments;
+        type AnimatedSeries = {
+          key: string;
+          fill: Color;
+          top: { x: number; y: number }[];
+          bottom: { x: number; y: number }[];
+        };
+        const series = new Map<string, AnimatedSeries>();
+        const orderKeys: string[] = [];
+        for (let i = 0; i < segments.length; i++) {
+          const seg = segments[i]!;
+          const toX = xFn(xAes.fn(seg.datum, seg.datumIndex));
+          const toY0 = yContinuous(seg.base);
+          const toY1 = yContinuous(seg.top);
+          const fromIndex = anim.matchIndex(`${rowKey(seg.datum, seg.datumIndex)}:${seg.key}`, i);
+          const fromX = fromIndex !== undefined ? anim.from.x[fromIndex] : NaN;
+          const fromY0 = fromIndex !== undefined ? (anim.from.r?.[fromIndex] ?? NaN) : NaN;
+          const fromY1 = fromIndex !== undefined ? anim.from.y[fromIndex] : NaN;
+          const px =
+            Number.isFinite(fromX) && Number.isFinite(toX) ? fromX + (toX - fromX) * anim.t : toX;
+          const py0 =
+            Number.isFinite(fromY0) && Number.isFinite(toY0)
+              ? fromY0 + (toY0 - fromY0) * anim.t
+              : toY0;
+          const py1 =
+            Number.isFinite(fromY1) && Number.isFinite(toY1)
+              ? fromY1 + (toY1 - fromY1) * anim.t
+              : toY1;
+          if (!Number.isFinite(px) || !Number.isFinite(py0) || !Number.isFinite(py1)) continue;
+          let bucket = series.get(seg.key);
+          if (!bucket) {
+            const toFill = alphaize(colorFn(seg.key), baseFillAlpha);
+            const fill =
+              fromIndex !== undefined
+                ? lerpColor(
+                    {
+                      r: anim.from.rgba[fromIndex * 4]!,
+                      g: anim.from.rgba[fromIndex * 4 + 1]!,
+                      b: anim.from.rgba[fromIndex * 4 + 2]!,
+                      a: anim.from.rgba[fromIndex * 4 + 3]!,
+                    },
+                    toFill,
+                    anim.t,
+                  )
+                : { ...toFill, a: toFill.a * anim.t };
+            bucket = { key: seg.key, fill, top: [], bottom: [] };
+            series.set(seg.key, bucket);
+            orderKeys.push(seg.key);
+          }
+          // Project the top and bottom edge vertices independently through
+          // the active coord. Cartesian: identity.
+          const projTop = coord.project({ x: px, y: py1 });
+          const projBottom = coord.project({ x: px, y: py0 });
+          bucket.top.push({ x: plot.topLeft.x + projTop.x, y: plot.topLeft.y + projTop.y });
+          bucket.bottom.push({
+            x: plot.topLeft.x + projBottom.x,
+            y: plot.topLeft.y + projBottom.y,
+          });
+        }
+        builders.push(
+          inlineMark((layer) => {
+            for (const key of orderKeys) {
+              const s = series.get(key)!;
+              if (s.top.length < 2) continue;
+              const points = [...s.top];
+              for (let i = s.bottom.length - 1; i >= 0; i--) points.push(s.bottom[i]!);
+              pushFilledPolygon(layer, points, { fill: s.fill, stroke, strokeWidth });
+            }
+          }, segments.length),
+        );
+      } else {
+        // Static (non-animated) stacked path. `stackedAreaMark` owns the
+        // top/bottom polygon construction via `x` callback + `valueScale`.
+        // Under `coordCartesian()` projection is the identity — projecting
+        // only one axis here would produce a half-projected result under
+        // polar, so we leave the mark unprojected for Phase 1 and let the
+        // Phase 3 polar coord swap in a different mark factory entirely.
+        const mark = stackedAreaMark<T, string>(data, [...activeKeys], {
+          x: (d, i) => xFn(xAes.fn(d, i)),
+          valueScale: yContinuous,
+          color: (key) => alphaize(colorFn(key), baseFillAlpha),
+          offset,
+          order: options.order,
+          stroke,
+          strokeWidth,
+        });
+        builders.push(wrapMark(mark, plot.topLeft));
+      }
+
+      // Hover halo + selection rings on stacked-area segment top edge.
+      const drawSegmentHalo = (i: number, key: string) => {
+        const seg = stackedSegments.find((s) => s.datumIndex === i && s.key === key);
+        if (!seg) return;
+        const xv = xAes.fn(seg.datum, seg.datumIndex);
+        if (xv == null) return;
+        const rawX = xFn(xv);
+        const rawY = yContinuous(seg.top);
+        if (!Number.isFinite(rawX) || !Number.isFinite(rawY)) return;
+        const projected = coord.project({ x: rawX, y: rawY });
+        const cx = plot.topLeft.x + projected.x;
+        const cy = plot.topLeft.y + projected.y;
+        const ringColor = colorFn(key);
+        builders.push(inlineMark((layer) => haloRing(layer, cx, cy, 6, ringColor, 2)));
+      };
+      if (
+        ctx.hovered &&
+        ctx.hovered.geomKind === "area" &&
+        ctx.hovered.data === data &&
+        ctx.hovered.seriesKey
+      ) {
+        drawSegmentHalo(ctx.hovered.dataIndex, ctx.hovered.seriesKey);
+      }
+      const stackedSelected = selectedSegmentsFor(ctx, "area");
+      if (stackedSelected) {
+        for (const { dataIndex: i, seriesKey: key } of stackedSelected) {
+          if (key) drawSegmentHalo(i, key);
+        }
+      }
+      return builders;
+    },
+    compileHitTest(ctx: CompileContext<T>): CompiledHitTest<T> | null {
+      const { data, scales, plot, hidden } = ctx;
+      if (data.length === 0) return null;
+      const coord = resolveCoord(ctx);
+
+      const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+      const xScale = scales.x.fn;
+      const yScale = scales.y.fn;
+      const ox = plot.topLeft.x;
+      const oy = plot.topLeft.y;
+      const positionsList: number[] = [];
+      const dataIndexList: number[] = [];
+      const seriesKeyList: (string | undefined)[] = [];
+
+      if (!isStacked) {
+        const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+        const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+        for (let i = 0; i < data.length; i++) {
+          const d = data[i]!;
+          if (hidden && colorAes && hidden.has(String(colorAes.fn(d, i)))) continue;
+          const xv = xAes.fn(d, i);
+          const yv = yAes.fn(d, i);
+          if (xv == null || yv == null) continue;
+          const rawX = xScale(xv);
+          const rawY = yScale(yv);
+          if (!Number.isFinite(rawX) || !Number.isFinite(rawY)) continue;
+          const projected = coord.project({ x: rawX, y: rawY });
+          positionsList.push(ox + projected.x, oy + projected.y);
+          dataIndexList.push(i);
+          seriesKeyList.push(undefined);
+        }
+      } else {
+        const keys = channels.y as readonly (keyof T & string)[];
+        const activeKeys = hidden ? keys.filter((k) => !hidden.has(k)) : keys;
+        const segments = stack(data, [...activeKeys] as string[], {
+          offset: options.position === "fill" ? "expand" : "zero",
+          order: options.order,
+        });
+        for (const seg of segments) {
+          const xv = xAes.fn(seg.datum, seg.datumIndex);
+          if (xv == null) continue;
+          const rawX = xScale(xv);
+          const rawY = yScale(seg.top);
+          if (!Number.isFinite(rawX) || !Number.isFinite(rawY)) continue;
+          const projected = coord.project({ x: rawX, y: rawY });
+          positionsList.push(ox + projected.x, oy + projected.y);
+          dataIndexList.push(seg.datumIndex);
+          seriesKeyList.push(seg.key);
+        }
+      }
+      const n = dataIndexList.length;
+      if (n === 0) return null;
+      const positions = Float32Array.from(positionsList);
+      const dataIndex = Int32Array.from(dataIndexList);
+
+      const channelsMap: ResolvedChannelMap<T> = {
+        x: xAes,
+        y: !isStacked ? resolveAes<T, unknown>(channels.y as Aes<T, unknown>) : undefined,
+        color: !isStacked && channels.color ? resolveAes<T, unknown>(channels.color) : undefined,
+      };
+
+      const pickRadius = options.nearestX ? Math.max(plot.width, plot.height) : 12;
+      return {
+        geomKind: "area",
+        label: options.label,
+        positions: positions.subarray(0, n * 2),
+        dataIndex: dataIndex.subarray(0, n),
+        seriesKey: seriesKeyList,
+        pickRadius,
+        pickAxis: options.nearestX ? "x" : undefined,
+        channels: channelsMap,
+        data,
+      };
+    },
+    captureFrame(ctx: CompileContext<T>): GeomFrame | null {
+      const { data, scales, theme } = ctx;
+      if (data.length === 0) return null;
+
+      const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+      const xFn = scales.x.fn;
+      const yScale = scales.y.fn;
+      const count = isStacked
+        ? (channels.y as readonly (keyof T & string)[]).reduce(
+            (sum, key) => sum + (ctx.hidden?.has(key) ? 0 : data.length),
+            0,
+          )
+        : data.length;
+      const x = new Float32Array(count);
+      const y = new Float32Array(count);
+      const rgba = new Float32Array(count * 4);
+      const a = new Float32Array(count);
+      // r stores the pixel baseline (y0) for lerp.
+      const r = new Float32Array(count);
+      const ids = ctx.transitionKey ? Array.from<string>({ length: count }) : undefined;
+      if (!isStacked) {
+        const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+        const yBaseline = yScale(0);
+        const areaFill = options.fill ?? defaultMarkFill(theme);
+        const resolvedFill = alphaize(areaFill, theme.marks.fillAlpha);
+        for (let i = 0; i < count; i++) {
+          const d = data[i]!;
+          const xv = xAes.fn(d, i);
+          const yv = yAes.fn(d, i);
+          const px = xFn(xv);
+          const py = yScale(yv);
+          x[i] = Number.isFinite(px) ? px : NaN;
+          y[i] = Number.isFinite(py) ? py : NaN;
+          r[i] = yBaseline;
+          rgba[i * 4] = resolvedFill.r;
+          rgba[i * 4 + 1] = resolvedFill.g;
+          rgba[i * 4 + 2] = resolvedFill.b;
+          rgba[i * 4 + 3] = resolvedFill.a;
+          a[i] = resolvedFill.a;
+          if (ids) ids[i] = ctx.transitionKey!(d, i);
+        }
+      } else {
+        const keys = channels.y as readonly (keyof T & string)[];
+        const activeKeys = ctx.hidden ? keys.filter((k) => !ctx.hidden!.has(k)) : keys;
+        const colorFn = seriesColor(scales.color, theme.palettes.categorical, [
+          ...keys,
+        ] as string[]);
+        const segments = stack(data, [...activeKeys] as string[], {
+          offset: options.position === "fill" ? "expand" : "zero",
+          order: options.order,
+        });
+        let n = 0;
+        for (const seg of segments) {
+          const px = xFn(xAes.fn(seg.datum, seg.datumIndex));
+          const py = yScale(seg.top);
+          const py0 = yScale(seg.base);
+          const fill = alphaize(colorFn(seg.key), theme.marks.fillAlpha);
+          x[n] = Number.isFinite(px) ? px : NaN;
+          y[n] = Number.isFinite(py) ? py : NaN;
+          r[n] = Number.isFinite(py0) ? py0 : NaN;
+          rgba[n * 4] = fill.r;
+          rgba[n * 4 + 1] = fill.g;
+          rgba[n * 4 + 2] = fill.b;
+          rgba[n * 4 + 3] = fill.a;
+          a[n] = fill.a;
+          if (ids) ids[n] = `${ctx.transitionKey!(seg.datum, seg.datumIndex)}:${seg.key}`;
+          n++;
+        }
+      }
+
+      return { count, x, y, rgba, a, r, ids };
+    },
+  };
+}

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

@@ -0,0 +1,27 @@
+import type { Color } from "insomni";
+import { type ColorOrAccent } from "../color-utils.ts";
+import type { Geom } from "./types.ts";
+export interface BandChannels {
+    x?: readonly [number | Date, number | Date];
+    y?: readonly [number | Date, number | Date];
+}
+export interface BandOptions {
+    /**
+     * Fill color. Accepts a literal {@link Color} or a theme accent key
+     * (`"positive" | "negative" | "warn" | "info"`); accent keys resolve through
+     * `theme.accents` and have `theme.marks.bandFillAlpha` applied unless
+     * {@link BandOptions.alpha} is set.
+     */
+    fill?: ColorOrAccent;
+    stroke?: ColorOrAccent;
+    strokeWidth?: number;
+    /**
+     * Override the fill alpha. Defaults to `theme.marks.bandFillAlpha` when
+     * `fill` is omitted or is an accent key; defaults to no override (use the
+     * color's own alpha) when `fill` is a literal {@link Color}.
+     */
+    alpha?: number;
+    label?: string;
+    labelColor?: Color;
+}
+export declare function band<T>(channels: BandChannels, options?: BandOptions): Geom<T>;

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

@@ -0,0 +1,57 @@
+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 { band } from "./band.ts";
+import type { CompileContext } from "./types.ts";
+
+interface Row {
+  v: number;
+}
+
+const data: Row[] = [{ v: 25 }, { v: 75 }];
+
+function makeCtx(rows: readonly Row[]): CompileContext<Row> {
+  const xAes = resolveAes<Row, unknown>("v");
+  const yAes = resolveAes<Row, unknown>("v");
+  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("band geom — compileHitTest", () => {
+  test("vertical band emits one hit at the band's center", () => {
+    const geom = band<Row>({ x: [25, 75] }, { label: "warn zone" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(hits.geomKind).toBe("band");
+    expect(hits.dataIndex.length).toBe(1);
+    // Band spans scaled x [0, 100]; center x = 50; +plot.x(50) = 100.
+    expect(hits.positions[0]).toBeCloseTo(100, 3);
+    // y centered in plot frame: 30 + 100 = 130.
+    expect(hits.positions[1]).toBeCloseTo(130, 3);
+    expect(hits.label).toBe("warn zone");
+  });
+
+  test("horizontal band centers x in the plot frame", () => {
+    const geom = band<Row>({ y: [25, 75] });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    // x centered: 50 + 50 = 100.
+    expect(hits.positions[0]).toBeCloseTo(100, 3);
+  });
+
+  test("pickRadius covers half the band's larger extent", () => {
+    const geom = band<Row>({ x: [25, 75] });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    // halfY = plot.height/2 = 100 (off-axis = full height) > halfX = 50.
+    expect(hits.pickRadius).toBeCloseTo(100, 3);
+  });
+});