insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/bar.ts

@@ -0,0 +1,1054 @@
+// ---------------------------------------------------------------------------
+// bar geom
+// ---------------------------------------------------------------------------
+
+import { lerpColor, type Color, type Layer } from "insomni";
+import {
+  categoricalBarMark,
+  groupedBarMark,
+  stackedBarMark,
+  type BarBorderStyle,
+  type BarOrientation,
+  type StackOffset,
+  type StackOrder,
+} from "../../marks.ts";
+import { stack } from "../../marks/stack.ts";
+import { valueLabelMark } from "../../annotations.ts";
+import { groupedBandScale, type BandScale, type ContinuousScale } from "../../scales.ts";
+import type { Aes } from "../aes.ts";
+import { resolveAes } from "../aes.ts";
+import { alphaize, seriesColor } from "../color-utils.ts";
+import { barSwatch } from "../../legend.ts";
+import type {
+  CompileContext,
+  CompiledHitTest,
+  Geom,
+  GeomFrame,
+  GeomHoverDecorator,
+  HoveredHit,
+  ResolvedChannelMap,
+  ScaleHints,
+} from "./types.ts";
+import {
+  inlineMark,
+  resolveCoord,
+  resolveFillAlpha,
+  defaultMarkFill,
+  selectChannels,
+  selectedIndicesFor,
+  selectedSegmentsFor,
+  selectionActive,
+  SELECTION_DIM_ALPHA,
+  wrapMark,
+} from "./_mark.ts";
+import { emphasisContext } from "./emphasis.ts";
+import { barRect } from "./_shape.ts";
+import { DEFAULT_GROUP_PADDING } from "./_categorical.ts";
+import type { MarkBuilder } from "../../marks.ts";
+
+export type BarPosition = "identity" | "stack" | "dodge" | "fill";
+
+export interface BarChannels<T> {
+  x: Aes<T, string | number | Date>;
+  /**
+   * Single column → simple bars (one per category). Array of column keys →
+   * multi-series bars (stacked / dodged / 100% stacked).
+   *
+   * For horizontal layouts (`orientation: "x"`) the single-column form carries
+   * the band category, so a string is accepted; the value axis then lives on
+   * `x`.
+   */
+  y: Aes<T, string | number | Date> | readonly (keyof T & string)[];
+  color?: Aes<T, unknown>;
+}
+
+export interface BarOptions<T = unknown> {
+  orientation?: BarOrientation;
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  cornerRadius?: number;
+  /**
+   * Border treatment shared across every bar (or segment, for stacked/dodged
+   * layouts). See {@link BarBorderStyle}.
+   */
+  borderStyle?: BarBorderStyle;
+  /**
+   * Multi-series layout. Only meaningful when `y` (or `x`) is an array of keys.
+   * - `"stack"` (default for arrays) — segments stacked from 0
+   * - `"dodge"` — bars side-by-side within each category
+   * - `"fill"` — stacked, normalized to [0, 1]
+   * - `"identity"` — each datum drawn at its raw value
+   */
+  position?: BarPosition;
+  order?: StackOrder;
+  label?: string;
+  /** Inner-band padding for `position: 'dodge'`. Default 0.05. */
+  groupPadding?: number;
+  /** If set, render a label above each bar with the per-category total. */
+  showTotals?: (total: number, datum: T, datumIndex: number) => string;
+  /**
+   * If set, render a label per-bar (or per-segment for stacked / fill) with
+   * the segment's value. For `fill`, the supplied `value` is normalized
+   * `[0, 1]`; for other positions it's the raw segment value. `key` is the
+   * column name for multi-series bars, `undefined` for simple bars.
+   */
+  showValues?: (value: number, datum: T, datumIndex: number, key?: string) => string;
+  /** Override label color. */
+  labelColor?: Color;
+  /** Override label font size. */
+  labelFontSize?: number;
+}
+
+export function bar<T>(channels: BarChannels<T>, options: BarOptions<T> = {}): Geom<T> {
+  const isMultiSeries = Array.isArray(channels.y);
+  const position: BarPosition = options.position ?? (isMultiSeries ? "stack" : "identity");
+  // Bars baseline at 0 on their value axis. Orientation isn't known until
+  // compile-time (depends on scale types); for non-multi-series we hint
+  // both axes — band scales ignore numeric hints, so only the value axis
+  // is actually anchored.
+  const scaleHints: ScaleHints = isMultiSeries
+    ? position === "fill"
+      ? { y: { domain: [0, 1] } }
+      : { y: { includeZero: true } }
+    : { x: { includeZero: true }, y: { includeZero: true } };
+  return {
+    kind: "bar",
+    channels: { x: channels.x, y: channels.y, color: channels.color },
+    label: options.label,
+    scaleHints,
+    legendSwatch: (color) => barSwatch({ fill: color, size: 12 }),
+    compile(ctx: CompileContext<T>) {
+      const { data, scales, plot, theme, atlas } = ctx;
+      const coord = resolveCoord(ctx);
+      // Route a (bandStart, valuePx) pair through the active coord, returning
+      // the projected pair in plot-frame pixel space. Under `coordCartesian()`
+      // this is the identity. Polar (Phase 3) replaces this geom's mark
+      // factories outright (bars → annular sectors), so the projection here
+      // affects only the geom-owned overlays (labels, halos, rings, hit-test).
+      const projectBand = (
+        orient: "x" | "y",
+        bandStart: number,
+        valuePx: number,
+      ): { bandStart: number; valuePx: number } => {
+        const projected =
+          orient === "y"
+            ? coord.project({ x: bandStart, y: valuePx })
+            : coord.project({ x: valuePx, y: bandStart });
+        return orient === "y"
+          ? { bandStart: projected.x, valuePx: projected.y }
+          : { bandStart: projected.y, valuePx: projected.x };
+      };
+      const cornerRadius = options.cornerRadius ?? theme.marks.barCornerRadius;
+      const stroke = options.stroke;
+      const strokeWidth = options.strokeWidth;
+
+      // Detect orientation from scale types unless overridden:
+      //   x is band, y is continuous → vertical (orientation "y")
+      //   x is continuous, y is band → horizontal (orientation "x")
+      const orientation: "x" | "y" =
+        options.orientation ??
+        (scales.x.type === "band" ? "y" : scales.y.type === "band" ? "x" : "y");
+
+      const { categoryChannel, valueChannel } = selectChannels(orientation, channels);
+      const categoryAes = resolveAes<T, unknown>(categoryChannel as Aes<T, unknown>);
+      const bandAxis = (
+        orientation === "y" ? scales.x.axisScale : scales.y.axisScale
+      ) as BandScale<string>;
+      const valueAxis = (
+        orientation === "y" ? scales.y.axisScale : scales.x.axisScale
+      ) as ContinuousScale;
+      const labelColor: Color = options.labelColor ?? theme.text.color;
+      const labelFontSize = options.labelFontSize ?? theme.marks.labelFontSize;
+      const anim = ctx.activeTransition;
+      const rowKey = (d: T, i: number) => (ctx.transitionKey ? ctx.transitionKey(d, i) : String(i));
+      const fromRowIndex = (d: T, i: number) => anim?.matchIndex(rowKey(d, i), i);
+      const fromSegmentIndex = (d: T, i: number, key: string, fallbackIndex?: number) =>
+        anim?.matchIndex(`${rowKey(d, i)}:${key}`, fallbackIndex);
+
+      if (!isMultiSeries) {
+        const valueAes = resolveAes<T, number>(valueChannel as Aes<T, number>);
+        const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+        const colorScaleFn = scales.color?.fn;
+        const baseFill: Color = options.fill ?? defaultMarkFill(theme);
+        const baseFillFor =
+          colorAes && colorScaleFn
+            ? (d: T, i: number) => alphaize(colorScaleFn(colorAes.fn(d, i)), theme.marks.fillAlpha)
+            : alphaize(baseFill, theme.marks.fillAlpha);
+        const selectedSet = selectedIndicesFor(ctx, "bar");
+        const dim = selectionActive(ctx);
+        // Hover emphasis — the dim-others treatment rides the core's GPU emphasis
+        // uniform (P5-T3): tag each bar with a stable per-row key; the mount fades
+        // non-focused bars with no marks recompile. Selection dim stays compile-
+        // time (it forces a full recompile already). No compile-time hover dim.
+        const emph = emphasisContext(ctx, "bar");
+        const fill = dim
+          ? (d: T, i: number) => {
+              const c = typeof baseFillFor === "function" ? baseFillFor(d, i) : baseFillFor;
+              return selectedSet?.has(i) ? c : alphaize(c, SELECTION_DIM_ALPHA);
+            }
+          : baseFillFor;
+        const isHidden = (d: T, i: number) => {
+          if (!ctx.hidden || !colorAes) return false;
+          return ctx.hidden.has(String(colorAes.fn(d, i)));
+        };
+
+        const mark = categoricalBarMark<T, string>(data, {
+          orientation,
+          category: (d, i) => String(categoryAes.fn(d, i)),
+          value: (d, i) => {
+            if (isHidden(d, i)) return NaN;
+            const toV = valueAes.fn(d, i);
+            if (!anim) return toV;
+            const fromIndex = fromRowIndex(d, i);
+            if (fromIndex === undefined) return toV * anim.t;
+            const fromV = anim.from.r?.[fromIndex];
+            if (fromV === undefined || !Number.isFinite(fromV)) return toV;
+            return fromV + (toV - fromV) * anim.t;
+          },
+          categoryScale: bandAxis,
+          valueScale: valueAxis,
+          fill: anim
+            ? (d: T, i: number): Color => {
+                const toFill =
+                  typeof fill === "function"
+                    ? (fill as (d: T, i: number) => Color)(d, i)
+                    : (fill as Color);
+                const fromIndex = fromRowIndex(d, i);
+                if (fromIndex === undefined) return { ...toFill, a: toFill.a * anim.t };
+                const fromFill: Color = {
+                  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]!,
+                };
+                return lerpColor(fromFill, toFill, anim.t);
+              }
+            : fill,
+          stroke,
+          strokeWidth,
+          cornerRadius,
+          borderStyle: options.borderStyle,
+          emphasisKey: emph ? (_d, i) => emph.keyFor(i) : undefined,
+        });
+        const builders: MarkBuilder[] = [wrapMark(mark, plot.topLeft, data.length)];
+
+        // Selection rings — outline each selected bar. Reuses the bbox math
+        // from the hover halo above.
+        if (selectedSet) {
+          for (const i of selectedSet) {
+            const d = data[i];
+            if (d === undefined) continue;
+            const cv = categoryAes.fn(d, i);
+            const vv = valueAes.fn(d, i);
+            if (cv == null || vv == null || !Number.isFinite(vv)) continue;
+            const projVal = projectBand(orientation, bandAxis(String(cv)), valueAxis(vv));
+            const projBase = projectBand(orientation, bandAxis(String(cv)), valueAxis(0));
+            const rect = barRect(
+              orientation,
+              projVal.bandStart,
+              bandAxis.bandwidth(),
+              projVal.valuePx,
+              projBase.valuePx,
+              plot.topLeft,
+            );
+            if (!rect) continue;
+            const ringColor: Color =
+              colorAes && colorScaleFn
+                ? colorScaleFn(colorAes.fn(d, i))
+                : (options.fill ?? defaultMarkFill(theme));
+            builders.push(
+              inlineMark((layer) =>
+                layer.pushRect({
+                  ...rect,
+                  cornerRadius,
+                  stroke: ringColor,
+                  strokeWidth: 2,
+                }),
+              ),
+            );
+          }
+        }
+
+        const simpleLabel = options.showValues ?? options.showTotals;
+        if (atlas && simpleLabel) {
+          const bw = bandAxis.bandwidth();
+          const projectSimpleLabel = (d: T, i: number): { x: number; y: number } => {
+            const bandStart = bandAxis(String(categoryAes.fn(d, i))) + bw / 2;
+            const valuePx = valueAxis(valueAes.fn(d, i));
+            const proj = projectBand(orientation, bandStart, valuePx);
+            return orientation === "y"
+              ? { x: proj.bandStart, y: proj.valuePx }
+              : { x: proj.valuePx, y: proj.bandStart };
+          };
+          const labelMark = valueLabelMark(data, {
+            x: (d, i) => projectSimpleLabel(d, i).x,
+            y: (d, i) => projectSimpleLabel(d, i).y,
+            text: (d, i) => simpleLabel(valueAes.fn(d, i), d, i),
+            color: labelColor,
+            fontSize: labelFontSize,
+            align: orientation === "y" ? "center" : "left",
+            offset: orientation === "y" ? { y: -6 } : { x: 6 },
+          });
+          builders.push(wrapMark(labelMark, plot.topLeft, data.length));
+        }
+        return builders;
+      }
+
+      // ----- multi-series -----
+      const keys = valueChannel 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 fillFor = seriesColor(scales.color, theme.palettes.categorical, [...keys] as string[]);
+      // Pre-compute fills once: `fillFor` runs through a Map lookup + palette
+      // call on every invocation, and the inner mark builders call it per
+      // datum × key. Caching collapses that to one lookup per series.
+      const fillByKey = new Map<string, Color>();
+      for (const k of activeKeys) fillByKey.set(k, fillFor(k));
+      const builders: ReturnType<typeof wrapMark>[] = [];
+      // When a selection is active, the base mark renders uniformly dimmed and
+      // we re-overlay the selected segments at full color on top (the underlying
+      // mark APIs only accept per-key fills, not per-(datum, key) — overlays
+      // are simpler than threading a richer color callback through).
+      const dimMulti = selectionActive(ctx);
+      const baseFillAlpha = resolveFillAlpha(dimMulti, theme);
+      // GPU hover emphasis (P5-T3) — one key per (datum, series) segment. The
+      // ordinal packs the segment index into the geom's key band; the resolver
+      // (`emphasisResolution` below) recomputes the SAME ordinal from a hit's
+      // (dataIndex, seriesKey) using this keys list. Stable across the full keys
+      // (not activeKeys) so hiding a series doesn't renumber the rest.
+      const emphMulti = emphasisContext(ctx, "bar", (hit) =>
+        multiEmphasisOrdinal(hit.dataIndex, hit.seriesKey, keys),
+      );
+      const segmentEmphasisKey = (dataIndex: number, key: string): number | undefined => {
+        if (!emphMulti) return undefined;
+        const ord = multiEmphasisOrdinal(dataIndex, key, keys);
+        return ord === null ? undefined : emphMulti.keyFor(ord);
+      };
+
+      if (position === "dodge") {
+        const inner = groupedBandScale<string, string>(bandAxis, [...activeKeys] as string[], {
+          padding: options.groupPadding ?? DEFAULT_GROUP_PADDING,
+        });
+        const mark = groupedBarMark<T, string, string>(data, {
+          orientation,
+          category: (d, i) => String(categoryAes.fn(d, i)),
+          groupedScale: inner,
+          valueScale: valueAxis,
+          value: (d, key, datumIndex) => {
+            const toV = (d as Record<string, number>)[key] ?? 0;
+            if (!anim) return toV;
+            const subIndex = activeKeys.indexOf(key as keyof T & string);
+            const fallbackIndex =
+              subIndex >= 0 ? datumIndex * activeKeys.length + subIndex : undefined;
+            const fromIndex = fromSegmentIndex(d, datumIndex, key, fallbackIndex);
+            if (fromIndex === undefined) return toV * anim.t;
+            const fromV = anim.from.r?.[fromIndex];
+            if (fromV === undefined || !Number.isFinite(fromV)) return toV;
+            return fromV + (toV - fromV) * anim.t;
+          },
+          color: (key) => {
+            const toFill = alphaize(fillByKey.get(key) ?? fillFor(key), baseFillAlpha);
+            if (!anim) return toFill;
+            const probeDatum = data[0];
+            if (probeDatum === undefined) return toFill;
+            const subIndex = activeKeys.indexOf(key as keyof T & string);
+            const fromIndex = fromSegmentIndex(
+              probeDatum,
+              0,
+              key,
+              subIndex >= 0 ? subIndex : undefined,
+            );
+            if (fromIndex === undefined) return { ...toFill, a: toFill.a * anim.t };
+            const fromFill: Color = {
+              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]!,
+            };
+            return lerpColor(fromFill, toFill, anim.t);
+          },
+          cornerRadius,
+          stroke,
+          strokeWidth,
+          borderStyle: options.borderStyle,
+          emphasisKey: (d, key, datumIndex) => segmentEmphasisKey(datumIndex, key),
+        });
+        builders.push(wrapMark(mark, plot.topLeft));
+
+        const ibw = inner.bandwidth();
+        const baseline = valueAxis(0);
+        const drawSegmentRing = (i: number, key: string, overlayFill: boolean) => {
+          const d = data[i];
+          if (d === undefined) return;
+          const cv = categoryAes.fn(d, i);
+          const vv = (d as Record<string, number>)[key];
+          if (cv == null || vv == null || !Number.isFinite(vv)) return;
+          const projVal = projectBand(orientation, inner(String(cv), key), valueAxis(vv));
+          const projBase = projectBand(orientation, inner(String(cv), key), baseline);
+          const rect = barRect(
+            orientation,
+            projVal.bandStart,
+            ibw,
+            projVal.valuePx,
+            projBase.valuePx,
+            plot.topLeft,
+          );
+          if (!rect) return;
+          const ringColor = fillByKey.get(key) ?? fillFor(key);
+          const overlay = overlayFill ? alphaize(ringColor, theme.marks.fillAlpha) : undefined;
+          builders.push(
+            inlineMark((layer) =>
+              layer.pushRect({
+                ...rect,
+                cornerRadius,
+                fill: overlay,
+                stroke: ringColor,
+                strokeWidth: 2,
+              }),
+            ),
+          );
+        };
+        const dodgeSelected = selectedSegmentsFor(ctx, "bar");
+        if (dodgeSelected) {
+          for (const { dataIndex: i, seriesKey: key } of dodgeSelected) {
+            if (key) drawSegmentRing(i, key, dimMulti);
+          }
+        }
+
+        if (atlas && options.showValues) {
+          const fmt = options.showValues;
+          const bw = inner.bandwidth();
+          for (const key of activeKeys) {
+            const projectDodgeLabel = (d: T, i: number): { x: number; y: number } => {
+              const bandStart = inner(String(categoryAes.fn(d, i)), key) + bw / 2;
+              const valuePx = valueAxis((d as Record<string, number>)[key] ?? 0);
+              const proj = projectBand(orientation, bandStart, valuePx);
+              return orientation === "y"
+                ? { x: proj.bandStart, y: proj.valuePx }
+                : { x: proj.valuePx, y: proj.bandStart };
+            };
+            const labelMark = valueLabelMark(data, {
+              x: (d, i) => projectDodgeLabel(d, i).x,
+              y: (d, i) => projectDodgeLabel(d, i).y,
+              text: (d, i) => fmt((d as Record<string, number>)[key] ?? 0, d, i, key),
+              color: labelColor,
+              fontSize: labelFontSize,
+              align: orientation === "y" ? "center" : "left",
+              offset: orientation === "y" ? { y: -4 } : { x: 4 },
+            });
+            builders.push(wrapMark(labelMark, plot.topLeft, data.length));
+          }
+        }
+      } else {
+        const offset: StackOffset = position === "fill" ? "expand" : "zero";
+        const stackedSegmentsCurrent = stack(data, [...activeKeys] as string[], {
+          offset,
+          order: options.order,
+        });
+        const stackedMark = stackedBarMark<T, string, string>(data, [...activeKeys], {
+          orientation,
+          category: (d, i) => String(categoryAes.fn(d, i)),
+          categoryScale: bandAxis,
+          valueScale: valueAxis,
+          value: (d, key, datumIndex) => {
+            const toV = (d as Record<string, number>)[key] ?? 0;
+            if (!anim) return toV;
+            const fallbackIndex = stackedSegmentsCurrent.findIndex(
+              (seg) => seg.datumIndex === datumIndex && seg.key === key,
+            );
+            const fromIndex = fromSegmentIndex(
+              d,
+              datumIndex,
+              key,
+              fallbackIndex >= 0 ? fallbackIndex : undefined,
+            );
+            if (fromIndex === undefined) return toV * anim.t;
+            const fromV = anim.from.r?.[fromIndex];
+            if (fromV === undefined || !Number.isFinite(fromV)) return toV;
+            return fromV + (toV - fromV) * anim.t;
+          },
+          color: (key, seg) => {
+            const toFill = alphaize(fillByKey.get(key) ?? fillFor(key), baseFillAlpha);
+            if (!anim) return toFill;
+            const fallbackIndex = stackedSegmentsCurrent.findIndex(
+              (s) => s.datumIndex === seg.datumIndex && s.key === key,
+            );
+            const fromIndex = fromSegmentIndex(
+              seg.datum,
+              seg.datumIndex,
+              key,
+              fallbackIndex >= 0 ? fallbackIndex : undefined,
+            );
+            if (fromIndex === undefined) return { ...toFill, a: toFill.a * anim.t };
+            const fromFill: Color = {
+              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]!,
+            };
+            return lerpColor(fromFill, toFill, anim.t);
+          },
+          offset,
+          order: options.order,
+          cornerRadius,
+          stroke,
+          strokeWidth,
+          borderStyle: options.borderStyle,
+          emphasisKey: (key, seg) => segmentEmphasisKey(seg.datumIndex, key),
+        });
+        builders.push(wrapMark(stackedMark, plot.topLeft));
+
+        const stackBw = bandAxis.bandwidth();
+        const drawStackedRing = (i: number, key: string, overlayFill: boolean) => {
+          const seg = stackedSegmentsCurrent.find((s) => s.datumIndex === i && s.key === key);
+          if (!seg) return;
+          const cat = categoryAes.fn(seg.datum, seg.datumIndex);
+          if (cat == null) return;
+          const bandStart = bandAxis(String(cat));
+          const basePx = valueAxis(seg.base);
+          const topPx = valueAxis(seg.top);
+          if (!Number.isFinite(bandStart) || !Number.isFinite(basePx) || !Number.isFinite(topPx))
+            return;
+          const projBase = projectBand(orientation, bandStart, basePx);
+          const projTop = projectBand(orientation, bandStart, topPx);
+          const ox = plot.topLeft.x;
+          const oy = plot.topLeft.y;
+          const lo = Math.min(projBase.valuePx, projTop.valuePx);
+          const span = Math.abs(projTop.valuePx - projBase.valuePx);
+          const projectedBand = projBase.bandStart;
+          const rx = ox + (orientation === "y" ? projectedBand : lo);
+          const ry = oy + (orientation === "y" ? lo : projectedBand);
+          const rw = orientation === "y" ? stackBw : span;
+          const rh = orientation === "y" ? span : stackBw;
+          const ringColor = fillByKey.get(key) ?? fillFor(key);
+          const overlay = overlayFill ? alphaize(ringColor, theme.marks.fillAlpha) : undefined;
+          builders.push(
+            inlineMark((layer) =>
+              layer.pushRect({
+                x: rx,
+                y: ry,
+                width: rw,
+                height: rh,
+                cornerRadius,
+                fill: overlay,
+                stroke: ringColor,
+                strokeWidth: 2,
+              }),
+            ),
+          );
+        };
+        const stackedSelected = selectedSegmentsFor(ctx, "bar");
+        if (stackedSelected) {
+          for (const { dataIndex: i, seriesKey: key } of stackedSelected) {
+            if (key) drawStackedRing(i, key, dimMulti);
+          }
+        }
+
+        if (atlas && options.showValues) {
+          const fmt = options.showValues;
+          const segs = stackedMark.segments;
+          const bw = bandAxis.bandwidth();
+          const projectSegLabel = (seg: (typeof segs)[number]): { x: number; y: number } => {
+            const cat = String(categoryAes.fn(seg.datum, seg.datumIndex));
+            const bandStart = bandAxis(cat) + bw / 2;
+            const valuePx = valueAxis((seg.base + seg.top) / 2);
+            const proj = projectBand(orientation, bandStart, valuePx);
+            return orientation === "y"
+              ? { x: proj.bandStart, y: proj.valuePx }
+              : { x: proj.valuePx, y: proj.bandStart };
+          };
+          const segLabel = valueLabelMark(segs, {
+            x: (seg) => projectSegLabel(seg).x,
+            y: (seg) => projectSegLabel(seg).y,
+            text: (seg) => fmt(seg.value, seg.datum, seg.datumIndex, seg.key),
+            color: labelColor,
+            fontSize: labelFontSize,
+            align: "center",
+            offset: { x: 0, y: 0 },
+          });
+          builders.push(wrapMark(segLabel, plot.topLeft, segs.length));
+        }
+
+        if (atlas && options.showTotals && position !== "fill") {
+          const fmt = options.showTotals;
+          const totals = data.map((d) =>
+            activeKeys.reduce((s, k) => s + ((d as Record<string, number>)[k] ?? 0), 0),
+          );
+          const bw = bandAxis.bandwidth();
+          const projectTotalLabel = (d: T, i: number): { x: number; y: number } => {
+            const bandStart = bandAxis(String(categoryAes.fn(d, i))) + bw / 2;
+            const valuePx = valueAxis(totals[i] ?? 0);
+            const proj = projectBand(orientation, bandStart, valuePx);
+            return orientation === "y"
+              ? { x: proj.bandStart, y: proj.valuePx }
+              : { x: proj.valuePx, y: proj.bandStart };
+          };
+          const totalLabel = valueLabelMark(data, {
+            x: (d, i) => projectTotalLabel(d, i).x,
+            y: (d, i) => projectTotalLabel(d, i).y,
+            text: (d, i) => fmt(totals[i] ?? 0, d, i),
+            color: labelColor,
+            fontSize: labelFontSize,
+            align: orientation === "y" ? "center" : "left",
+            offset: orientation === "y" ? { y: -6 } : { x: 6 },
+          });
+          builders.push(wrapMark(totalLabel, plot.topLeft, data.length));
+        }
+      }
+
+      return builders;
+    },
+    emphasisResolution(ctx) {
+      if (!isMultiSeries) {
+        // Single bars: ordinal = dataIndex (the default).
+        return emphasisContext(ctx, "bar")?.resolver() ?? null;
+      }
+      // Multi-series: pack (dataIndex, seriesKey) through the stable keys list.
+      const keys = channels.y as readonly (keyof T & string)[];
+      return (
+        emphasisContext(ctx, "bar", (hit) =>
+          multiEmphasisOrdinal(hit.dataIndex, hit.seriesKey, keys as readonly string[]),
+        )?.resolver() ?? null
+      );
+    },
+    hoverDecoration(ctx: CompileContext<T>): GeomHoverDecorator | null {
+      // Focus halo on the hovered bar — recovered from the old snap path's
+      // compile-time outline (deleted in e6d5643). Now an OVERLAY decorator: the
+      // mount replays it into the live overlay layer (NO marks recompile), so the
+      // halo reads on top of the (GPU-dimmed) marks. Overlay shapes leave the
+      // default emphasisKey 0 ⇒ EXEMPT ⇒ the halo stays full-strength while the
+      // other bars dim. Mirrors point.ts's decorator (re-derive geometry, stroke
+      // width/color from theme.interactions.hover with the same fallback shape).
+      const { data, plot } = ctx;
+      if (data.length === 0) return null;
+      const coord = resolveCoord(ctx);
+      const hoverCfg = ctx.theme.interactions.hover;
+
+      const orientation: "x" | "y" =
+        options.orientation ??
+        (ctx.scales.x.type === "band" ? "y" : ctx.scales.y.type === "band" ? "x" : "y");
+      const { categoryChannel, valueChannel } = selectChannels(orientation, channels);
+      const categoryAes = resolveAes<T, unknown>(categoryChannel as Aes<T, unknown>);
+      const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+      const colorScaleFn = ctx.scales.color?.fn;
+      const bandAxis = (
+        orientation === "y" ? ctx.scales.x.axisScale : ctx.scales.y.axisScale
+      ) as BandScale<string>;
+      const valueAxis = (
+        orientation === "y" ? ctx.scales.y.axisScale : ctx.scales.x.axisScale
+      ) as ContinuousScale;
+      const cornerRadius = options.cornerRadius ?? ctx.theme.marks.barCornerRadius;
+      const fillFor = isMultiSeries
+        ? seriesColor(ctx.scales.color, ctx.theme.palettes.categorical, [
+            ...(valueChannel as readonly (keyof T & string)[]),
+          ] as string[])
+        : undefined;
+      // Same band-projection helper compile uses (coord.project; Cartesian = id).
+      const projectBand = (bandStart: number, valuePx: number) => {
+        const p =
+          orientation === "y"
+            ? coord.project({ x: bandStart, y: valuePx })
+            : coord.project({ x: valuePx, y: bandStart });
+        return orientation === "y"
+          ? { bandStart: p.x, valuePx: p.y }
+          : { bandStart: p.y, valuePx: p.x };
+      };
+
+      const haloFor = (
+        bandStart: number,
+        bandwidth: number,
+        valuePx: number,
+        ringColor: Color,
+        layer: Layer,
+      ): void => {
+        const projVal = projectBand(bandStart, valuePx);
+        const projBase = projectBand(bandStart, valueAxis(0));
+        const rect = barRect(
+          orientation,
+          projVal.bandStart,
+          bandwidth,
+          projVal.valuePx,
+          projBase.valuePx,
+          plot.topLeft,
+        );
+        if (!rect) return;
+        layer.pushRect({
+          ...rect,
+          cornerRadius,
+          stroke: hoverCfg.haloColor ?? ringColor,
+          strokeWidth: hoverCfg.haloStrokeWidth,
+        });
+      };
+
+      return {
+        geomKind: "bar",
+        data,
+        decorate(hit: HoveredHit, layer: Layer): void {
+          if (!hoverCfg.enabled || hit.data !== data) return;
+          const i = hit.dataIndex;
+          const d = data[i];
+          if (d === undefined) return;
+          const cv = categoryAes.fn(d, i);
+          if (cv == null) return;
+
+          if (!isMultiSeries) {
+            const valueAes = resolveAes<T, number>(valueChannel as Aes<T, number>);
+            const vv = valueAes.fn(d, i);
+            if (vv == null || !Number.isFinite(vv)) return;
+            const ringColor: Color =
+              colorAes && colorScaleFn
+                ? colorScaleFn(colorAes.fn(d, i))
+                : (options.fill ?? defaultMarkFill(ctx.theme));
+            haloFor(bandAxis(String(cv)), bandAxis.bandwidth(), valueAxis(vv), ringColor, layer);
+            return;
+          }
+
+          // Multi-series: the hit's seriesKey identifies the segment.
+          const key = hit.seriesKey;
+          if (key === undefined) return;
+          const ringColor = fillFor!(key);
+          if (position === "dodge") {
+            const keys = valueChannel as readonly (keyof T & string)[];
+            const activeKeys = ctx.hidden ? keys.filter((k) => !ctx.hidden!.has(k)) : keys;
+            const inner = groupedBandScale<string, string>(bandAxis, [...activeKeys] as string[], {
+              padding: options.groupPadding ?? DEFAULT_GROUP_PADDING,
+            });
+            const vv = (d as Record<string, number>)[key];
+            if (vv == null || !Number.isFinite(vv)) return;
+            haloFor(inner(String(cv), key), inner.bandwidth(), valueAxis(vv), ringColor, layer);
+          } else {
+            // stack / fill: re-stack to find this segment's [base, top].
+            const keys = valueChannel as readonly (keyof T & string)[];
+            const activeKeys = ctx.hidden ? keys.filter((k) => !ctx.hidden!.has(k)) : keys;
+            const segs = stack(data, [...activeKeys] as string[], {
+              offset: position === "fill" ? "expand" : "zero",
+              order: options.order,
+            });
+            const seg = segs.find((s) => s.datumIndex === i && s.key === key);
+            if (!seg) return;
+            const bandStart = bandAxis(String(cv));
+            const basePx = valueAxis(seg.base);
+            const topPx = valueAxis(seg.top);
+            if (
+              !Number.isFinite(bandStart) ||
+              !Number.isFinite(basePx) ||
+              !Number.isFinite(topPx)
+            ) {
+              return;
+            }
+            const projBase = projectBand(bandStart, basePx);
+            const projTop = projectBand(bandStart, topPx);
+            const ox = plot.topLeft.x;
+            const oy = plot.topLeft.y;
+            const lo = Math.min(projBase.valuePx, projTop.valuePx);
+            const span = Math.abs(projTop.valuePx - projBase.valuePx);
+            const bw = bandAxis.bandwidth();
+            layer.pushRect({
+              x: ox + (orientation === "y" ? projBase.bandStart : lo),
+              y: oy + (orientation === "y" ? lo : projBase.bandStart),
+              width: orientation === "y" ? bw : span,
+              height: orientation === "y" ? span : bw,
+              cornerRadius,
+              stroke: hoverCfg.haloColor ?? ringColor,
+              strokeWidth: hoverCfg.haloStrokeWidth,
+            });
+          }
+        },
+      };
+    },
+    compileHitTest(ctx: CompileContext<T>): CompiledHitTest<T> | null {
+      const { data, scales, plot, hidden } = ctx;
+      if (data.length === 0) return null;
+      const coord = resolveCoord(ctx);
+
+      const orientation: "x" | "y" =
+        options.orientation ??
+        (scales.x.type === "band" ? "y" : scales.y.type === "band" ? "x" : "y");
+
+      const { categoryChannel, valueChannel } = selectChannels(orientation, channels);
+      const categoryAes = resolveAes<T, unknown>(categoryChannel as Aes<T, unknown>);
+      const simpleValueAes = !isMultiSeries
+        ? resolveAes<T, number>(valueChannel as Aes<T, number>)
+        : undefined;
+      const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+
+      const bandAxis = (
+        orientation === "y" ? scales.x.axisScale : scales.y.axisScale
+      ) as BandScale<string>;
+      const valueAxis = (
+        orientation === "y" ? scales.y.axisScale : scales.x.axisScale
+      ) as ContinuousScale;
+      const bw = bandAxis.bandwidth();
+      const baseline = valueAxis(0);
+
+      const ox = plot.topLeft.x;
+      const oy = plot.topLeft.y;
+      const positionsList: number[] = [];
+      const rectsList: number[] = [];
+      const dataIndexList: number[] = [];
+      const seriesKeyList: (string | undefined)[] = [];
+      let maxHalfHeight = 0;
+
+      // Helper: push one hit entry given the bar's band-start, bar-bw, and
+      // the value-axis pixel extent [lo, hi]. Computes both position and rect
+      // for whole-bar footprint hit testing.
+      const pushEntry = (
+        bandStart: number,
+        barBw: number,
+        valueLo: number,
+        valueHi: number,
+        datumIndex: number,
+        seriesK: string | undefined,
+      ) => {
+        const bandCenter = bandStart + barBw / 2;
+        const valueCenter = (valueLo + valueHi) / 2;
+        const halfHeight = (valueHi - valueLo) / 2;
+        if (halfHeight > maxHalfHeight) maxHalfHeight = halfHeight;
+        // Hit-test positions go through `coord.project` so tooltips land on
+        // the visible mark under any coord. Cartesian: identity.
+        if (orientation === "y") {
+          const centerProj = coord.project({ x: bandCenter, y: valueCenter });
+          const cornerProj = coord.project({ x: bandStart, y: valueLo });
+          positionsList.push(ox + centerProj.x, oy + centerProj.y);
+          rectsList.push(ox + cornerProj.x, oy + cornerProj.y, barBw, valueHi - valueLo);
+        } else {
+          const centerProj = coord.project({ x: valueCenter, y: bandCenter });
+          const cornerProj = coord.project({ x: valueLo, y: bandStart });
+          positionsList.push(ox + centerProj.x, oy + centerProj.y);
+          rectsList.push(ox + cornerProj.x, oy + cornerProj.y, valueHi - valueLo, barBw);
+        }
+        dataIndexList.push(datumIndex);
+        seriesKeyList.push(seriesK);
+      };
+
+      if (!isMultiSeries) {
+        for (let i = 0; i < data.length; i++) {
+          const d = data[i]!;
+          if (hidden && colorAes && hidden.has(String(colorAes.fn(d, i)))) continue;
+          const cv = categoryAes.fn(d, i);
+          const vv = simpleValueAes!.fn(d, i);
+          if (cv == null || vv == null || !Number.isFinite(vv)) continue;
+          const bandStart = bandAxis(String(cv));
+          if (!Number.isFinite(bandStart)) continue;
+          const valuePx = valueAxis(vv);
+          if (!Number.isFinite(valuePx)) continue;
+          const lo = Math.min(baseline, valuePx);
+          const hi = Math.max(baseline, valuePx);
+          pushEntry(bandStart, bw, lo, hi, i, undefined);
+        }
+      } else {
+        const keys = valueChannel as readonly (keyof T & string)[];
+        const activeKeys = hidden ? keys.filter((k) => !hidden.has(k)) : keys;
+        if (position === "dodge") {
+          const inner = groupedBandScale<string, string>(bandAxis, [...activeKeys] as string[], {
+            padding: options.groupPadding ?? DEFAULT_GROUP_PADDING,
+          });
+          const innerBw = inner.bandwidth();
+          for (let i = 0; i < data.length; i++) {
+            const d = data[i]!;
+            const cat = categoryAes.fn(d, i);
+            if (cat == null) continue;
+            for (const key of activeKeys) {
+              const vv = (d as Record<string, number>)[key] ?? 0;
+              if (!Number.isFinite(vv)) continue;
+              const bandStart = inner(String(cat), key);
+              if (!Number.isFinite(bandStart)) continue;
+              const valuePx = valueAxis(vv);
+              if (!Number.isFinite(valuePx)) continue;
+              const lo = Math.min(baseline, valuePx);
+              const hi = Math.max(baseline, valuePx);
+              pushEntry(bandStart, innerBw, lo, hi, i, key);
+            }
+          }
+        } else {
+          const segments = stack(data, [...activeKeys] as string[], {
+            offset: position === "fill" ? "expand" : "zero",
+            order: options.order,
+          });
+          for (const seg of segments) {
+            const cat = categoryAes.fn(seg.datum, seg.datumIndex);
+            if (cat == null) continue;
+            const bandStart = bandAxis(String(cat));
+            if (!Number.isFinite(bandStart)) continue;
+            const basePx = valueAxis(seg.base);
+            const topPx = valueAxis(seg.top);
+            if (!Number.isFinite(basePx) || !Number.isFinite(topPx)) continue;
+            const lo = Math.min(basePx, topPx);
+            const hi = Math.max(basePx, topPx);
+            pushEntry(bandStart, bw, lo, hi, seg.datumIndex, seg.key);
+          }
+        }
+      }
+      const n = dataIndexList.length;
+      if (n === 0) return null;
+      const positions = Float32Array.from(positionsList);
+      const rects = Float32Array.from(rectsList);
+      const dataIndex = Int32Array.from(dataIndexList);
+
+      const channelsMap: ResolvedChannelMap<T> = {
+        x:
+          orientation === "y"
+            ? categoryAes
+            : isMultiSeries
+              ? undefined
+              : (simpleValueAes as ResolvedAesUnknown<T>),
+        y:
+          orientation === "y"
+            ? isMultiSeries
+              ? undefined
+              : (simpleValueAes as ResolvedAesUnknown<T>)
+            : categoryAes,
+        color: colorAes,
+      };
+
+      return {
+        geomKind: "bar",
+        label: options.label,
+        positions: positions.subarray(0, n * 2),
+        rects: rects.subarray(0, n * 4),
+        dataIndex: dataIndex.subarray(0, n),
+        seriesKey: seriesKeyList,
+        pickRadius: Math.max(bw / 2, maxHalfHeight),
+        channels: channelsMap,
+        data,
+      };
+    },
+    captureFrame(ctx: CompileContext<T>): GeomFrame | null {
+      const { data, scales, theme } = ctx;
+      if (data.length === 0) return null;
+
+      const orientation: "x" | "y" =
+        options.orientation ??
+        (scales.x.type === "band" ? "y" : scales.y.type === "band" ? "x" : "y");
+
+      const { categoryChannel, valueChannel } = selectChannels(orientation, channels);
+      const categoryAes = resolveAes<T, unknown>(categoryChannel as Aes<T, unknown>);
+      const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+      const colorScaleFn = scales.color?.fn;
+      const baseFill: Color = options.fill ?? defaultMarkFill(theme);
+      const fillFor = seriesColor(scales.color, theme.palettes.categorical, [
+        ...(isMultiSeries ? (valueChannel as readonly (keyof T & string)[]) : []),
+      ] as string[]);
+
+      const bandAxis = (
+        orientation === "y" ? scales.x.axisScale : scales.y.axisScale
+      ) as BandScale<string>;
+      const bw = bandAxis.bandwidth();
+      const hiddenKeys = ctx.hidden;
+      const count = isMultiSeries
+        ? (valueChannel as readonly (keyof T & string)[]).reduce(
+            (sum, key) => sum + (hiddenKeys?.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 raw domain value for bar height (used for lerp).
+      const r = new Float32Array(count);
+      const ids = ctx.transitionKey ? Array.from<string>({ length: count }) : undefined;
+
+      if (!isMultiSeries) {
+        const valueAes = resolveAes<T, number>(valueChannel as Aes<T, number>);
+        for (let i = 0; i < count; i++) {
+          const d = data[i]!;
+          const cv = categoryAes.fn(d, i);
+          const bandStart = bandAxis(String(cv));
+          const bandCenter = Number.isFinite(bandStart) ? bandStart + bw / 2 : NaN;
+          x[i] = orientation === "y" ? bandCenter : NaN;
+          y[i] = orientation === "y" ? NaN : bandCenter;
+          r[i] = valueAes.fn(d, i);
+          const c: Color = colorAes && colorScaleFn ? colorScaleFn(colorAes.fn(d, i)) : baseFill;
+          const alpha = theme.marks.fillAlpha;
+          rgba[i * 4] = c.r;
+          rgba[i * 4 + 1] = c.g;
+          rgba[i * 4 + 2] = c.b;
+          rgba[i * 4 + 3] = c.a * alpha;
+          a[i] = alpha;
+          if (ids) ids[i] = ctx.transitionKey!(d, i);
+        }
+      } else {
+        const keys = valueChannel as readonly (keyof T & string)[];
+        const activeKeys = hiddenKeys ? keys.filter((k) => !hiddenKeys.has(k)) : keys;
+        const alpha = theme.marks.fillAlpha;
+        // Cache fills per series to avoid per-datum scale lookup.
+        const fillByKey = new Map<string, Color>();
+        for (const k of activeKeys) fillByKey.set(k, fillFor(k));
+        let n = 0;
+        if (position === "dodge") {
+          const inner = groupedBandScale<string, string>(bandAxis, [...activeKeys] as string[], {
+            padding: options.groupPadding ?? DEFAULT_GROUP_PADDING,
+          });
+          for (let i = 0; i < data.length; i++) {
+            const d = data[i]!;
+            const cat = categoryAes.fn(d, i);
+            for (const key of activeKeys) {
+              const bandStart = cat == null ? NaN : inner(String(cat), key);
+              const bandCenter = Number.isFinite(bandStart)
+                ? bandStart + inner.bandwidth() / 2
+                : NaN;
+              x[n] = orientation === "y" ? bandCenter : NaN;
+              y[n] = orientation === "y" ? NaN : bandCenter;
+              r[n] = (d as Record<string, number>)[key] ?? 0;
+              const c = fillByKey.get(key) ?? fillFor(key);
+              rgba[n * 4] = c.r;
+              rgba[n * 4 + 1] = c.g;
+              rgba[n * 4 + 2] = c.b;
+              rgba[n * 4 + 3] = c.a * alpha;
+              a[n] = alpha;
+              if (ids) ids[n] = `${ctx.transitionKey!(d, i)}:${key}`;
+              n++;
+            }
+          }
+        } else {
+          const segments = stack(data, [...activeKeys] as string[], {
+            offset: position === "fill" ? "expand" : "zero",
+            order: options.order,
+          });
+          for (const seg of segments) {
+            const cat = categoryAes.fn(seg.datum, seg.datumIndex);
+            const bandStart = cat == null ? NaN : bandAxis(String(cat));
+            const bandCenter = Number.isFinite(bandStart) ? bandStart + bw / 2 : NaN;
+            x[n] = orientation === "y" ? bandCenter : NaN;
+            y[n] = orientation === "y" ? NaN : bandCenter;
+            r[n] = (seg.datum as Record<string, number>)[seg.key] ?? 0;
+            const c = fillByKey.get(seg.key) ?? fillFor(seg.key);
+            rgba[n * 4] = c.r;
+            rgba[n * 4 + 1] = c.g;
+            rgba[n * 4 + 2] = c.b;
+            rgba[n * 4 + 3] = c.a * alpha;
+            a[n] = alpha;
+            if (ids) ids[n] = `${ctx.transitionKey!(seg.datum, seg.datumIndex)}:${seg.key}`;
+            n++;
+          }
+        }
+      }
+
+      return { count, x, y, rgba, a, r, ids };
+    },
+  };
+}
+
+type ResolvedAesUnknown<T> = import("../aes.ts").ResolvedAes<T, unknown>;
+
+/**
+ * Pack a multi-series bar segment's (dataIndex, seriesKey) into a single
+ * emphasis ordinal: `dataIndex * keys.length + seriesIndex`. `seriesIndex` is
+ * the key's position in the geom's STABLE full keys list (not `activeKeys`), so
+ * toggling a series in/out of view never renumbers another segment's key. A hit
+ * whose `seriesKey` isn't in `keys` (or is absent) returns `null` (focuses
+ * nothing). Tagging and hit-resolution call this identically.
+ */
+function multiEmphasisOrdinal(
+  dataIndex: number,
+  seriesKey: string | undefined,
+  keys: readonly string[],
+): number | null {
+  if (seriesKey === undefined) return null;
+  const seriesIndex = keys.indexOf(seriesKey);
+  if (seriesIndex < 0) return null;
+  return dataIndex * keys.length + seriesIndex;
+}