insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/point.ts

@@ -0,0 +1,545 @@
+// ---------------------------------------------------------------------------
+// point geom
+// ---------------------------------------------------------------------------
+
+import { lerpColor, type Color, type Layer } from "insomni";
+import {
+  pointMark,
+  type MarkBuilder,
+  type PointBorderStyle,
+  type PointShapeKind,
+} from "../../marks.ts";
+import type { Aes } from "../aes.ts";
+import { resolveAes } from "../aes.ts";
+import { alphaize, withAlpha } from "../color-utils.ts";
+import type {
+  CompileContext,
+  CompiledHitTest,
+  Geom,
+  GeomFrame,
+  GeomHoverDecorator,
+  HoveredHit,
+  ResolvedChannelMap,
+} from "./types.ts";
+import {
+  defaultMarkFill,
+  haloRing,
+  inlineMark,
+  resolveCoord,
+  selectedIndicesFor,
+  selectionActive,
+  SELECTION_DIM_ALPHA,
+  wrapMark,
+} from "./_mark.ts";
+import { DEFAULT_OVERLAY_SCALE } from "../constants.ts";
+
+export interface PointChannels<T> {
+  x: Aes<T, number | Date>;
+  y: Aes<T, number | Date>;
+  color?: Aes<T, unknown>;
+  size?: Aes<T, number>;
+  /**
+   * Categorical shape mapping. Values are looked up in the active shape scale
+   * — by default a built-in palette (`POINT_SHAPE_PALETTE`). Pass a literal
+   * `PointShapeKind` accessor and `.scale("shape", { palette: [...] })` to
+   * customize. When the value is already a `PointShapeKind`, it's used as-is.
+   */
+  shape?: Aes<T, unknown>;
+  alpha?: Aes<T, number>;
+  /**
+   * Per-datum border treatment. The accessor may return either a resolved
+   * {@link PointBorderStyle} (used as-is) or any other categorical value that
+   * gets routed through the active `borderStyle` scale (default palette:
+   * `solid`, `open`, `dashed`, `dotted`). Configure a custom mapping with
+   * `.scale("borderStyle", { palette: [...] })`.
+   */
+  borderStyle?: Aes<T, unknown>;
+  /**
+   * Optional secondary glyph overlaid on the base shape at the same anchor.
+   * Accepts either a resolved {@link PointShapeKind}/`null`, or a categorical
+   * value routed through the `overlayGlyph` scale (default palette starts
+   * with `null` so the most-common category gets no overlay). Configure with
+   * `.scale("overlayGlyph", { palette: [...] })`.
+   */
+  overlayGlyph?: Aes<T, unknown>;
+  /** Overlay radius as a fraction of base radius. Default `0.6`. */
+  overlayScale?: Aes<T, number>;
+}
+
+export interface PointOptions {
+  /** Constant fill if color channel is absent. */
+  fill?: Color;
+  /** Constant point radius if size channel is absent. */
+  radius?: number;
+  /** Override theme stroke. */
+  stroke?: Color | null;
+  /** Override theme stroke width. */
+  strokeWidth?: number;
+  /** Constant shape if shape channel is absent. */
+  shape?: PointShapeKind;
+  /** Constant border style if border-style channel is absent. */
+  borderStyle?: PointBorderStyle;
+  /** Constant overlay glyph if overlay-glyph channel is absent. */
+  overlayGlyph?: PointShapeKind | null;
+  /** Constant overlay scale if overlay-scale channel is absent. */
+  overlayScale?: number;
+  /** Display label for legend (defaults to color column name). */
+  label?: string;
+}
+
+const isBorderStyleLiteral = (v: unknown): v is PointBorderStyle =>
+  v === "solid" || v === "dashed" || v === "dotted" || v === "open";
+const isPointShapeLiteral = (v: unknown): v is PointShapeKind => {
+  if (typeof v !== "string") return false;
+  return (
+    v === "circle" ||
+    v === "square" ||
+    v === "triangle" ||
+    v === "diamond" ||
+    v === "circle-open" ||
+    v === "square-open" ||
+    v === "triangle-open" ||
+    v === "diamond-open" ||
+    v === "cross" ||
+    v === "plus" ||
+    v === "star"
+  );
+};
+
+/**
+ * Resolve the per-datum visual functions shared by `compile` (which wraps
+ * `radius` / `fill` / projection in transition lerps) and `hoverDecoration`
+ * (which re-emits a single glyph onto the overlay). Centralizing keeps the two
+ * paths from drifting on shape / border / overlay / fill resolution. The
+ * returned `radius` / `fill` are the *static* (non-animated) values; `compile`
+ * layers transition interpolation on top.
+ */
+function pointVisuals<T>(
+  channels: PointChannels<T>,
+  options: PointOptions,
+  ctx: CompileContext<T>,
+) {
+  const { scales, theme } = ctx;
+  const coord = resolveCoord(ctx);
+  const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+  const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+  const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+  const sizeAes = channels.size ? resolveAes<T, number>(channels.size) : undefined;
+  const alphaAes = channels.alpha ? resolveAes<T, number>(channels.alpha) : undefined;
+  const shapeAes = channels.shape ? resolveAes<T, unknown>(channels.shape) : undefined;
+  const borderStyleAes = channels.borderStyle
+    ? resolveAes<T, unknown>(channels.borderStyle)
+    : undefined;
+  const overlayGlyphAes = channels.overlayGlyph
+    ? resolveAes<T, unknown>(channels.overlayGlyph)
+    : undefined;
+  const overlayScaleAes = channels.overlayScale
+    ? resolveAes<T, number>(channels.overlayScale)
+    : undefined;
+
+  const baseFill: Color = options.fill ?? defaultMarkFill(theme);
+  const baseRadius = options.radius ?? theme.marks.pointRadius;
+  const baseShape: PointShapeKind = options.shape ?? "circle";
+  const stroke =
+    options.stroke === null ? undefined : (options.stroke ?? theme.marks.pointStroke ?? undefined);
+  const strokeWidth = options.strokeWidth ?? theme.marks.pointStrokeWidth;
+
+  const xScale = scales.x.fn;
+  const yScale = scales.y.fn;
+  const colorScale = scales.color?.fn;
+  const sizeScale = scales.size?.fn;
+  const alphaScale = scales.alpha?.fn;
+  const shapeScale = scales.shape?.fn;
+  const borderStyleScale = scales.borderStyle?.fn;
+  const overlayGlyphScale = scales.overlayGlyph?.fn;
+
+  const fill = (d: T, i: number): Color => {
+    const base: Color = colorAes && colorScale ? colorScale(colorAes.fn(d, i)) : baseFill;
+    if (alphaAes && alphaScale) return withAlpha(base, alphaScale(alphaAes.fn(d, i)));
+    return alphaize(base, theme.marks.fillAlpha);
+  };
+  const radius = (d: T, i: number): number =>
+    sizeAes && sizeScale ? (sizeScale(sizeAes.fn(d, i)) as number) || baseRadius : baseRadius;
+  const shape: (d: T, i: number) => PointShapeKind =
+    shapeAes && shapeScale
+      ? (d, i) => shapeScale(shapeAes.fn(d, i)) as PointShapeKind
+      : shapeAes
+        ? (d, i) => shapeAes.fn(d, i) as PointShapeKind
+        : () => baseShape;
+  const borderStyle: (d: T, i: number) => PointBorderStyle = borderStyleAes
+    ? (d, i) => {
+        const val = borderStyleAes.fn(d, i);
+        if (isBorderStyleLiteral(val)) return val;
+        return borderStyleScale ? (borderStyleScale(val) as PointBorderStyle) : "solid";
+      }
+    : () => options.borderStyle ?? "solid";
+  const overlayGlyph: (d: T, i: number) => PointShapeKind | null = overlayGlyphAes
+    ? (d, i) => {
+        const val = overlayGlyphAes.fn(d, i);
+        if (val === null || val === undefined) return null;
+        if (isPointShapeLiteral(val)) return val;
+        return overlayGlyphScale ? (overlayGlyphScale(val) as PointShapeKind | null) : null;
+      }
+    : () => options.overlayGlyph ?? null;
+  const overlayScale: (d: T, i: number) => number = overlayScaleAes
+    ? (d, i) => overlayScaleAes.fn(d, i)
+    : () => options.overlayScale ?? DEFAULT_OVERLAY_SCALE;
+
+  return {
+    coord,
+    xAes,
+    yAes,
+    colorAes,
+    sizeAes,
+    colorScale,
+    sizeScale,
+    baseFill,
+    baseRadius,
+    stroke,
+    strokeWidth,
+    xScale,
+    yScale,
+    fill,
+    radius,
+    shape,
+    borderStyle,
+    overlayGlyph,
+    overlayScale,
+  };
+}
+
+export function point<T>(channels: PointChannels<T>, options: PointOptions = {}): Geom<T> {
+  return {
+    kind: "point",
+    channels,
+    label: options.label,
+    compile(ctx: CompileContext<T>) {
+      const { data, plot } = ctx;
+      const v = pointVisuals(channels, options, ctx);
+      const {
+        coord,
+        xAes,
+        yAes,
+        colorAes,
+        sizeAes,
+        colorScale,
+        sizeScale,
+        baseFill,
+        baseRadius,
+        stroke,
+        strokeWidth,
+        xScale,
+        yScale,
+        fill: baseFillFor,
+        shape: shapeFn,
+        borderStyle: borderStyleFn,
+        overlayGlyph: overlayGlyphFn,
+        overlayScale: overlayScaleFn,
+      } = v;
+
+      // Selection dimming — when any row is selected anywhere, non-matching
+      // rows on this geom drop to SELECTION_DIM_ALPHA. Rows in `selectedSet`
+      // keep their natural alpha and pick up a stroke ring further down.
+      const selectedSet = selectedIndicesFor(ctx, "point");
+      const dim = selectionActive(ctx);
+      const fillFn = dim
+        ? (d: T, i: number): Color => {
+            const c = baseFillFor(d, i);
+            return selectedSet?.has(i) ? c : alphaize(c, SELECTION_DIM_ALPHA);
+          }
+        : baseFillFor;
+
+      const isHidden = (d: T, i: number) => {
+        if (!ctx.hidden || !colorAes) return false;
+        const val = colorAes.fn(d, i);
+        return ctx.hidden.has(String(val));
+      };
+
+      const anim = ctx.activeTransition;
+      const fromIndexFor = (d: T, i: number) =>
+        anim
+          ? ctx.transitionKey
+            ? anim.matchIndex(ctx.transitionKey(d, i), i)
+            : anim.matchIndex(String(i), i)
+          : undefined;
+
+      // Animated fill: lerp from the stored RGBA toward the current fill.
+      const animFill = anim
+        ? (d: T, i: number): Color => {
+            const toFill = fillFn(d, i);
+            const fromIndex = fromIndexFor(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);
+          }
+        : fillFn;
+
+      // Combined per-datum projection through the active coord. Under
+      // `coordCartesian()` `project` is the identity, so this returns the
+      // same plot-frame pixel pair we used to emit directly. Under polar
+      // (Phase 3) the (x, y) need to be projected as a single point — we
+      // compute both axes' lerped values and then project once per axis.
+      const projectXY = (d: T, i: number): { x: number; y: number } => {
+        if (isHidden(d, i)) return { x: NaN, y: NaN };
+        const toX = xScale(xAes.fn(d, i));
+        const toY = yScale(yAes.fn(d, i));
+        const fromIndex = fromIndexFor(d, i);
+        let px = toX;
+        let py = toY;
+        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]!)) {
+            py = anim.from.y[fromIndex]! + (toY - anim.from.y[fromIndex]!) * anim.t;
+          }
+        }
+        return coord.project({ x: px, y: py });
+      };
+      // Animated radius: lerp from the stored radius toward the current size.
+      const radiusFn: (d: T, i: number) => number =
+        sizeAes && sizeScale
+          ? (d, i) => {
+              const toR = v.radius(d, i);
+              if (!anim) return toR;
+              const fromIndex = fromIndexFor(d, i);
+              if (fromIndex === undefined) return toR * anim.t;
+              const fromR = anim.from.r?.[fromIndex] ?? toR;
+              return fromR + (toR - fromR) * anim.t;
+            }
+          : () => baseRadius;
+
+      const mark = pointMark(data, {
+        x: (d, i) => projectXY(d, i).x,
+        y: (d, i) => projectXY(d, i).y,
+        radius: radiusFn,
+        fill: animFill,
+        stroke,
+        strokeWidth,
+        shape: shapeFn,
+        borderStyle: borderStyleFn,
+        overlayGlyph: overlayGlyphFn,
+        overlayScale: overlayScaleFn,
+      });
+
+      const builders: MarkBuilder[] = [wrapMark(mark, plot.topLeft, data.length)];
+
+      // Hover focus (contrast halo + bring-to-front) is NOT drawn here — under
+      // partial redraw the marks layer is baked and never recompiles on hover,
+      // so it would never appear. It rides the cheap overlay path instead; see
+      // `hoverDecoration` below. Points also intentionally do not dim the rest
+      // on hover (sparse marks read fine with just the ring); only selection
+      // dims (see `dim` above).
+
+      // Selection rings — a stroke ring on each selected row.
+      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 = xScale(xv);
+          const rawY = yScale(yv);
+          if (!Number.isFinite(rawX) || !Number.isFinite(rawY)) continue;
+          const projected = coord.project({ x: rawX, y: rawY });
+          const r =
+            sizeAes && sizeScale ? Number(sizeScale(sizeAes.fn(d, i))) || baseRadius : baseRadius;
+          const ringColor: Color =
+            colorAes && colorScale ? colorScale(colorAes.fn(d, i)) : baseFill;
+          const cx = plot.topLeft.x + projected.x;
+          const cy = plot.topLeft.y + projected.y;
+          builders.push(inlineMark((layer) => haloRing(layer, cx, cy, r + 4, ringColor, 2)));
+        }
+      }
+
+      return builders;
+    },
+    hoverDecoration(ctx: CompileContext<T>): GeomHoverDecorator | null {
+      const { data, plot } = ctx;
+      if (data.length === 0) return null;
+      const v = pointVisuals(channels, options, ctx);
+      const hoverCfg = ctx.theme.interactions.hover;
+      const ringColor: Color = hoverCfg.haloColor ?? ctx.theme.text.color;
+      const origin = plot.topLeft;
+      return {
+        geomKind: "point",
+        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 xv = v.xAes.fn(d, i);
+          const yv = v.yAes.fn(d, i);
+          if (xv == null || yv == null) return;
+          const rawX = v.xScale(xv);
+          const rawY = v.yScale(yv);
+          if (!Number.isFinite(rawX) || !Number.isFinite(rawY)) return;
+          const p = v.coord.project({ x: rawX, y: rawY });
+          const r = v.radius(d, i);
+          // Contrast ring sits over the marks; the re-emitted glyph then draws
+          // on top so a point tucked under the trend line or behind a neighbor
+          // stays fully visible while focused. Un-dimmed fill keeps it vivid.
+          haloRing(
+            layer,
+            origin.x + p.x,
+            origin.y + p.y,
+            r + 4,
+            ringColor,
+            hoverCfg.haloStrokeWidth,
+          );
+          pointMark([d], {
+            x: () => p.x,
+            y: () => p.y,
+            radius: () => r,
+            fill: () => v.fill(d, i),
+            stroke: v.stroke,
+            strokeWidth: v.strokeWidth,
+            shape: () => v.shape(d, i),
+            borderStyle: () => v.borderStyle(d, i),
+            overlayGlyph: () => v.overlayGlyph(d, i),
+            overlayScale: () => v.overlayScale(d, i),
+          }).addTo(layer, origin);
+        },
+      };
+    },
+    compileHitTest(ctx: CompileContext<T>): CompiledHitTest<T> | null {
+      const { data, scales, plot, theme, hidden } = ctx;
+      if (data.length === 0) return null;
+      const coord = resolveCoord(ctx);
+
+      const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+      const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+      const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+      const sizeAes = channels.size
+        ? (resolveAes<T, number>(channels.size) as unknown as ResolvedAesUnknown<T>)
+        : undefined;
+      const shapeAes = channels.shape ? resolveAes<T, unknown>(channels.shape) : undefined;
+      const alphaAes = channels.alpha
+        ? (resolveAes<T, number>(channels.alpha) as unknown as ResolvedAesUnknown<T>)
+        : undefined;
+
+      const xScale = scales.x.fn;
+      const yScale = scales.y.fn;
+      const sizeScale = scales.size?.fn;
+      const baseRadius = options.radius ?? theme.marks.pointRadius;
+
+      const positions = new Float32Array(data.length * 2);
+      const dataIndex = new Int32Array(data.length);
+      const ox = plot.topLeft.x;
+      const oy = plot.topLeft.y;
+      let n = 0;
+      let maxRadius = baseRadius;
+      for (let i = 0; i < data.length; i++) {
+        const d = data[i]!;
+        const xv = xAes.fn(d, i);
+        const yv = yAes.fn(d, i);
+        if (xv == null || yv == null) continue;
+
+        if (hidden && colorAes && hidden.has(String(colorAes.fn(d, i)))) {
+          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 });
+        positions[n * 2] = ox + projected.x;
+        positions[n * 2 + 1] = oy + projected.y;
+        dataIndex[n] = i;
+        n++;
+        if (sizeAes && sizeScale) {
+          const r = sizeScale(sizeAes.fn(d, i));
+          if (typeof r === "number" && r > maxRadius) maxRadius = r;
+        }
+      }
+      if (n === 0) return null;
+
+      const channelsMap: ResolvedChannelMap<T> = {
+        x: xAes,
+        y: yAes,
+        color: colorAes,
+        size: sizeAes as ResolvedAesUnknown<T> | undefined,
+        shape: shapeAes,
+        alpha: alphaAes as ResolvedAesUnknown<T> | undefined,
+      };
+
+      return {
+        geomKind: "point",
+        label: options.label,
+        positions: positions.subarray(0, n * 2),
+        dataIndex: dataIndex.subarray(0, n),
+        pickRadius: Math.max(8, maxRadius + 4),
+        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 yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+      const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+      const sizeAes = channels.size ? resolveAes<T, number>(channels.size) : undefined;
+      const alphaAes = channels.alpha ? resolveAes<T, number>(channels.alpha) : undefined;
+
+      const xScale = scales.x.fn;
+      const yScale = scales.y.fn;
+      const colorScale = scales.color?.fn;
+      const sizeScale = scales.size?.fn;
+      const alphaScale = scales.alpha?.fn;
+
+      const baseRadius = options.radius ?? theme.marks.pointRadius;
+      const baseFill: Color = options.fill ?? defaultMarkFill(theme);
+
+      const count = data.length;
+      const x = new Float32Array(count);
+      const y = new Float32Array(count);
+      const rgba = new Float32Array(count * 4);
+      const a = new Float32Array(count);
+      const r = new Float32Array(count);
+      const transitionKey = ctx.transitionKey;
+      const ids = transitionKey ? Array.from<string>({ length: count }) : undefined;
+
+      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 = xScale(xv);
+        const py = yScale(yv);
+        x[i] = Number.isFinite(px) ? px : NaN;
+        y[i] = Number.isFinite(py) ? py : NaN;
+
+        // Radius
+        r[i] =
+          sizeAes && sizeScale ? (sizeScale(sizeAes.fn(d, i)) as number) || baseRadius : baseRadius;
+
+        // Color with alpha
+        const c: Color = colorAes && colorScale ? colorScale(colorAes.fn(d, i)) : baseFill;
+        const alpha =
+          alphaAes && alphaScale
+            ? (alphaScale(alphaAes.fn(d, i)) as number)
+            : 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 && transitionKey) ids[i] = transitionKey(d, i);
+      }
+
+      return { count, x, y, rgba, a, r, ids };
+    },
+  };
+}
+
+// Local alias to keep the cast site readable. SizeAes/AlphaAes resolve as
+// `ResolvedAes<T, number>` but the channel map types them as <T, unknown>.
+type ResolvedAesUnknown<T> = import("../aes.ts").ResolvedAes<T, unknown>;