insomni-plot 0.1.0-alpha.0

package/src/grammar/coord.ts

@@ -0,0 +1,619 @@
+// ---------------------------------------------------------------------------
+// Coord — coordinate system abstraction
+// ---------------------------------------------------------------------------
+// A `Coord` decides how plot-frame pixel positions (the output of x/y scales)
+// map onto layer-pixel space, and how axes are drawn for that mapping.
+//
+// Two coords ship today:
+//   - `coordCartesian()` — identity projection, current axis behavior.
+//   - `coordPolar()` / `coordRadial()` — (θ, r) → (cx + r·cosθ, cy + r·sinθ)
+//     with spokes + concentric-circle axes.
+//
+// The interface is shaped so polar lands without a second refactor:
+// `project` / `segment` are vertex-level hooks; `renderAxes` is the dispatch
+// point for non-Cartesian axis layouts; `handlePan` / `handleZoom` give polar
+// a place to translate pointer deltas into rotation / radial moves rather
+// than direct scale-domain rewrites.
+//
+// Polar is stateful: `bindFrame(plotFrame)` must be called before `project` /
+// `segment` / `renderAxes` so the projection knows where the plot centre is.
+// The pipeline calls this once per panel (faceted) or once per chart
+// (unfaceted). Cartesian's `bindFrame` is a no-op.
+
+import { type Color, type GlyphAtlas, type Layer, rgba } from "insomni";
+import { bottomAxis, leftAxis, type AxisOptions } from "../axis.ts";
+import type { ContinuousScale, TimeScale, BandScale } from "../scales.ts";
+import type { PositionScale } from "./scales.ts";
+import type { ScaleBundle } from "./geoms/types.ts";
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * Inputs to `Coord.renderAxes`. The pipeline owns scale construction and
+ * layout; the coord owns axis dispatch (Cartesian → bottom + left; polar →
+ * angular ring + radial spokes).
+ */
+export interface CoordAxesArgs {
+  axisLayer: Layer;
+  scales: ScaleBundle;
+  /** Inner plot frame — coords project relative to this. */
+  plotFrame: import("insomni").Frame;
+  /** True when the chart actually has a column on this channel. Skipped axes are not drawn. */
+  hasX: boolean;
+  hasY: boolean;
+  xAxisOptions: AxisOptions<unknown>;
+  yAxisOptions: AxisOptions<unknown>;
+  atlas: GlyphAtlas | undefined;
+}
+
+/**
+ * Inputs to `Coord.handlePan`. The mount / interactions layer passes a pointer
+ * delta in plot-frame pixels plus the active plot frame and a viewport handle
+ * the coord can use to mutate scale state. Cartesian delegates the whole
+ * thing to `viewport.panBy(dx, dy)`; polar decomposes into tangential
+ * (rotate `startAngle`) and radial (translate radius domain via the viewport).
+ */
+export interface CoordPanArgs {
+  dx: number;
+  dy: number;
+  /** Plot frame in absolute layer-pixel space (x, y are screen-space origin). */
+  plotFrame: import("insomni").Frame;
+  /** Viewport handle for scale-domain mutations. */
+  viewport: CoordViewportHandle;
+}
+
+export interface CoordZoomArgs {
+  /**
+   * Multiplicative zoom factor — `> 1` zooms in, `< 1` zooms out. May be a
+   * scalar (both axes) or a `{ x?, y? }` per-axis form (matches
+   * `viewport.zoomAt` and the masking that `bindDataViewport` performs).
+   */
+  factor: number | { x?: number; y?: number };
+  /** Cursor position in absolute layer-pixel space (matches `viewport.zoomAt`). */
+  cx: number;
+  cy: number;
+  plotFrame: import("insomni").Frame;
+  viewport: CoordViewportHandle;
+}
+
+/**
+ * Minimal facade over `DataViewport` so the coord can mutate scale state
+ * without depending on the full viewport surface. The two methods polar
+ * uses (`panBy`, `zoomAt`) match `DataViewport` semantics 1:1; Cartesian's
+ * implementation forwards through them so behavior is byte-identical to the
+ * pre-`handlePan` path.
+ */
+export interface CoordViewportHandle {
+  panBy(dxPx: number, dyPx: number): void;
+  zoomAt(anchorSx: number, anchorSy: number, factor: number | { x?: number; y?: number }): void;
+}
+
+/**
+ * A coordinate system. Polar / cartesian today; future room for log-polar /
+ * geographic projections behind the same interface.
+ */
+export interface Coord {
+  readonly kind: "cartesian" | "polar";
+  /**
+   * Bind the coord to a specific plot frame for the upcoming render.
+   * Polar's `project` / `segment` / `renderAxes` need the plot-frame
+   * dimensions and centre to compute (cx, cy) and the default outerRadius.
+   * Called by the pipeline once per panel (faceted) or once per chart
+   * (unfaceted) before any `project` / `renderAxes` call. Cartesian no-ops.
+   */
+  bindFrame(plotFrame: import("insomni").Frame): void;
+  /**
+   * Map a single point from plot-frame pixel space (0..plotFrame.width on x,
+   * 0..plotFrame.height on y — i.e. the raw output of `xScale.fn` / `yScale.fn`)
+   * to layer-pixel space (still relative to the plot frame's origin —
+   * `plot.topLeft` offsets are applied later by each geom).
+   *
+   * Cartesian: identity. Polar: (θ, r) → (cx + r·cosθ, cy + r·sinθ).
+   */
+  project(p: Point): Point;
+  /**
+   * Tessellate a polyline segment between two points in plot-frame pixel
+   * space. Returns the projected pixel points (including both endpoints).
+   * Cartesian returns `[project(p1), project(p2)]`; polar returns ~N points
+   * along the arc.
+   */
+  segment(p1: Point, p2: Point): Point[];
+  /**
+   * Render axes into `args.axisLayer`. Cartesian draws bottom (x) + left (y);
+   * polar draws an angular ring (spokes) + radial concentric circles.
+   */
+  renderAxes(args: CoordAxesArgs): void;
+  /**
+   * Inverse of `project`, for hit-testing / tooltips. Cartesian is the
+   * identity within the plot frame. Polar inverts (θ, r) and returns `null`
+   * when the projected point is outside `[innerRadius, outerRadius]`.
+   */
+  unproject(p: Point): Point | null;
+  /**
+   * Translate a pointer pan delta into scale-domain mutations.
+   * Cartesian forwards to `viewport.panBy(dx, dy)` — byte-identical to the
+   * pre-coord path. Polar decomposes the delta relative to the plot centre
+   * into tangential (rotate `startAngle`) and radial (translate the radius
+   * scale via `viewport.panBy(0, radial_dy)`) components.
+   */
+  handlePan(args: CoordPanArgs): void;
+  /**
+   * Translate a zoom factor + anchor into scale-domain mutations.
+   * Cartesian forwards to `viewport.zoomAt(cx, cy, factor)`. Polar scales the
+   * radius domain around the cursor's data-space radius; angle scale
+   * unchanged.
+   */
+  handleZoom(args: CoordZoomArgs): void;
+}
+
+// ---------------------------------------------------------------------------
+// coordCartesian
+// ---------------------------------------------------------------------------
+
+/**
+ * Default coord — identity projection, current axis behavior. Plot's existing
+ * pipeline behaves exactly as it did before the `Coord` interface was added
+ * when this is in use.
+ */
+export function coordCartesian(): Coord {
+  return cartesianSingleton;
+}
+
+const cartesianSingleton: Coord = {
+  kind: "cartesian",
+  bindFrame() {
+    // Cartesian is frame-agnostic — geoms apply `plot.topLeft` themselves.
+  },
+  project(p) {
+    return p;
+  },
+  segment(p1, p2) {
+    return [p1, p2];
+  },
+  renderAxes({ axisLayer, scales, plotFrame, hasX, hasY, xAxisOptions, yAxisOptions }) {
+    if (hasX) {
+      bottomAxis(
+        scales.x.axisScale as never,
+        {
+          ...xAxisOptions,
+          gridLength: plotFrame.height,
+          axisLineExtent: [0, plotFrame.width],
+        } as never,
+      ).addTo(axisLayer, plotFrame.bottomLeft);
+    }
+    if (hasY) {
+      leftAxis(
+        scales.y.axisScale as never,
+        {
+          ...yAxisOptions,
+          gridLength: plotFrame.width,
+          axisLineExtent: [0, plotFrame.height],
+        } as never,
+      ).addTo(axisLayer, plotFrame.topLeft);
+    }
+  },
+  unproject(p) {
+    return p;
+  },
+  handlePan({ dx, dy, viewport }) {
+    // Preserve existing behavior exactly: this is what `bindDataViewport`
+    // does today via a direct `viewport.panBy` call.
+    viewport.panBy(dx, dy);
+  },
+  handleZoom({ factor, cx, cy, viewport }) {
+    viewport.zoomAt(cx, cy, factor);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// coordPolar
+// ---------------------------------------------------------------------------
+
+const TWO_PI = Math.PI * 2;
+const DEFAULT_QUALITY = Math.PI / 180; // ~1°.
+
+export interface CoordPolarOptions {
+  /** Angle (radians) where the angular axis starts. Default `-π/2` (top). */
+  startAngle?: number;
+  /** Angle where the angular axis ends. Default `startAngle + 2π` (full circle). */
+  endAngle?: number;
+  /**
+   * Convenience for non-full-circle layouts: the gap (in radians) between
+   * `startAngle` and `endAngle`. `openAngle: 0` ↔ full circle;
+   * `openAngle: π/4` ↔ fan with a 45° gap at the start. Ignored when
+   * `endAngle` is provided.
+   */
+  openAngle?: number;
+  /** `1` (default, CCW) or `-1` (CW). */
+  direction?: 1 | -1;
+  /** Inner radius in pixels. Default `0`. */
+  innerRadius?: number;
+  /**
+   * Outer radius in pixels. Default `min(plotFrame.width, plotFrame.height) / 2`
+   * — resolved lazily on `bindFrame`.
+   */
+  outerRadius?: number;
+  /** Which channel maps to θ. Default `'y'` (gheatmap/circular-tree convention). */
+  angleChannel?: "x" | "y";
+  /** Angular tessellation step (radians) for `segment` and circular axes. Default ~1°. */
+  quality?: number;
+}
+
+/**
+ * Polar projection. See {@link CoordPolarOptions}.
+ *
+ * Each call returns a fresh stateful coord so the same `coordPolar({...})`
+ * expression can be reused safely. `bindFrame` mutates the centre and the
+ * default `outerRadius`.
+ */
+export function coordPolar(opts: CoordPolarOptions = {}): Coord {
+  const direction: 1 | -1 = opts.direction ?? 1;
+  const angleChannel: "x" | "y" = opts.angleChannel ?? "y";
+  const innerRadius = opts.innerRadius ?? 0;
+  const explicitOuter = opts.outerRadius;
+  const quality = opts.quality ?? DEFAULT_QUALITY;
+
+  let startAngle = opts.startAngle ?? -Math.PI / 2;
+  let endAngle: number;
+  if (opts.endAngle !== undefined) {
+    endAngle = opts.endAngle;
+  } else if (opts.openAngle !== undefined) {
+    endAngle = startAngle + (TWO_PI - opts.openAngle);
+  } else {
+    endAngle = startAngle + TWO_PI;
+  }
+
+  // Bound state. Updated by `bindFrame`.
+  let cx = 0;
+  let cy = 0;
+  let outerR = explicitOuter ?? 0;
+  let plotW = 0;
+  let plotH = 0;
+
+  function arcSpan(): number {
+    return endAngle - startAngle;
+  }
+
+  function angleAt(channelPixel: number, channelExtent: number): number {
+    const t = channelExtent > 0 ? channelPixel / channelExtent : 0;
+    return startAngle + direction * t * arcSpan();
+  }
+
+  function radiusAt(channelPixel: number, channelExtent: number): number {
+    const t = channelExtent > 0 ? channelPixel / channelExtent : 0;
+    return innerRadius + t * (outerR - innerRadius);
+  }
+
+  function project(p: Point): Point {
+    const theta = angleChannel === "x" ? angleAt(p.x, plotW) : angleAt(plotH - p.y, plotH);
+    const r = angleChannel === "x" ? radiusAt(plotH - p.y, plotH) : radiusAt(p.x, plotW);
+    return { x: cx + r * Math.cos(theta), y: cy + r * Math.sin(theta) };
+  }
+
+  function projectThetaR(theta: number, r: number): Point {
+    return { x: cx + r * Math.cos(theta), y: cy + r * Math.sin(theta) };
+  }
+
+  function pointToThetaR(p: Point): { theta: number; r: number } {
+    const theta = angleChannel === "x" ? angleAt(p.x, plotW) : angleAt(plotH - p.y, plotH);
+    const r = angleChannel === "x" ? radiusAt(plotH - p.y, plotH) : radiusAt(p.x, plotW);
+    return { theta, r };
+  }
+
+  function segment(p1: Point, p2: Point): Point[] {
+    const a = pointToThetaR(p1);
+    const b = pointToThetaR(p2);
+    const dTheta = b.theta - a.theta;
+    const dR = b.r - a.r;
+    // Radial line (same θ): straight spoke — no tessellation needed.
+    if (Math.abs(dTheta) < 1e-9) {
+      return [projectThetaR(a.theta, a.r), projectThetaR(b.theta, b.r)];
+    }
+    const absDTheta = Math.abs(dTheta);
+    const steps = Math.max(1, Math.ceil(absDTheta / quality));
+    const out: Point[] = Array.from({ length: steps + 1 });
+    for (let i = 0; i <= steps; i++) {
+      const t = i / steps;
+      const theta = a.theta + dTheta * t;
+      const r = a.r + dR * t; // arc when dR=0, oblique otherwise.
+      out[i] = projectThetaR(theta, r);
+    }
+    return out;
+  }
+
+  function unproject(p: Point): Point | null {
+    const dx = p.x - cx;
+    const dy = p.y - cy;
+    const r = Math.hypot(dx, dy);
+    if (r < innerRadius - 1e-6 || r > outerR + 1e-6) return null;
+    let theta = Math.atan2(dy, dx);
+    // Walk theta into the [startAngle, endAngle] half-open range (handling
+    // both 2π and partial-arc cases). For full circle this always succeeds.
+    const span = arcSpan();
+    const dirSpan = direction * span;
+    // Normalize offset from startAngle along the configured direction.
+    let off = (theta - startAngle) * direction;
+    // Bring into [0, 2π).
+    off = ((off % TWO_PI) + TWO_PI) % TWO_PI;
+    if (off > Math.abs(span) + 1e-6 && Math.abs(span) < TWO_PI - 1e-9) {
+      return null;
+    }
+    const tAngle = Math.abs(span) > 0 ? off / Math.abs(span) : 0;
+    const tRadial = outerR > innerRadius ? (r - innerRadius) / (outerR - innerRadius) : 0;
+    // Re-derive plot-frame pixel coords inverse to `project`.
+    const angleVal = tAngle * (angleChannel === "x" ? plotW : plotH);
+    const radialVal = tRadial * (angleChannel === "x" ? plotH : plotW);
+    if (angleChannel === "x") {
+      return { x: angleVal, y: plotH - radialVal };
+    }
+    return { x: radialVal, y: plotH - angleVal };
+    // Note: `dirSpan` reserved for future asymmetric direction handling.
+    void dirSpan;
+  }
+
+  function bindFrame(plotFrame: import("insomni").Frame): void {
+    plotW = plotFrame.width;
+    plotH = plotFrame.height;
+    cx = plotFrame.width / 2;
+    cy = plotFrame.height / 2;
+    outerR = explicitOuter ?? Math.max(0, Math.min(plotFrame.width, plotFrame.height) / 2);
+  }
+
+  function renderAxes(args: CoordAxesArgs): void {
+    bindFrame(args.plotFrame);
+    const origin = args.plotFrame.topLeft;
+    const axisLayer = args.axisLayer;
+
+    const angleScale = (angleChannel === "x" ? args.scales.x : args.scales.y) as
+      | PositionScale
+      | undefined;
+    const radiusScale = (angleChannel === "x" ? args.scales.y : args.scales.x) as
+      | PositionScale
+      | undefined;
+    const hasAngle = (angleChannel === "x" ? args.hasX : args.hasY) && !!angleScale;
+    const hasRadius = (angleChannel === "x" ? args.hasY : args.hasX) && !!radiusScale;
+
+    const angleOptions = angleChannel === "x" ? args.xAxisOptions : args.yAxisOptions;
+    const radiusOptions = angleChannel === "x" ? args.yAxisOptions : args.xAxisOptions;
+
+    const axisColor = angleOptions.tickColor ?? rgba(0.4, 0.4, 0.4, 1);
+    const gridColor =
+      (angleOptions.gridLines === false ? undefined : angleOptions.gridColor) ??
+      rgba(0.85, 0.85, 0.85, 1);
+    const axisWidth = angleOptions.axisLineWidth ?? 1;
+    const gridWidth = angleOptions.gridWidth ?? 1;
+
+    // ---- Radial axis (concentric circles) ----
+    if (hasRadius && radiusScale) {
+      const ticks = scaleTickValues(radiusScale.axisScale, radiusOptions);
+      for (const tick of ticks) {
+        const tPx = radiusScale.fn(tick);
+        if (!Number.isFinite(tPx)) continue;
+        const r = radiusAt(
+          angleChannel === "x" ? plotH - tPx : tPx,
+          angleChannel === "x" ? plotH : plotW,
+        );
+        if (r <= 0) continue;
+        drawArc(axisLayer, origin, cx, cy, r, startAngle, endAngle, quality, gridColor, gridWidth);
+      }
+    }
+
+    // ---- Angular axis (spokes from center to outerR) ----
+    if (hasAngle && angleScale) {
+      const ticks = scaleTickValues(angleScale.axisScale, angleOptions);
+      for (const tick of ticks) {
+        const tPx = angleScale.fn(tick);
+        if (!Number.isFinite(tPx)) continue;
+        const theta = angleAt(
+          angleChannel === "x" ? tPx : plotH - tPx,
+          angleChannel === "x" ? plotW : plotH,
+        );
+        const r0 = innerRadius;
+        const r1 = outerR;
+        const p0 = projectThetaR(theta, r0);
+        const p1 = projectThetaR(theta, r1);
+        pushLineAt(axisLayer, origin, p0, p1, axisColor, axisWidth);
+      }
+    }
+  }
+
+  function handlePan(args: CoordPanArgs): void {
+    const { dx, dy, plotFrame, viewport } = args;
+    // Plot-frame absolute centre.
+    const absCx = plotFrame.x + plotFrame.width / 2;
+    const absCy = plotFrame.y + plotFrame.height / 2;
+    // Use the *midpoint* of the drag (after the delta has been applied to the
+    // last pointer event) as the reference for tangential vs radial
+    // decomposition. The exact incremental delta is small enough that using
+    // the centre-to-current vector is a good approximation; bindDataViewport
+    // dispatches sub-frame deltas.
+    // Vector from centre to current pointer (approximate as start-of-drag
+    // pointer since we don't have it — use centre→delta-direction instead).
+    // For incremental decomposition we use the pointer's *frame-relative*
+    // position implied by combining frame centre with the delta direction.
+    // A simpler and well-defined decomposition: rotate by tangential
+    // (perpendicular to the radial vector at the *current* drag location,
+    // which we recover by treating (dx, dy) as the radial vector's projection
+    // onto an "average pointer" at frame centre + 0.5*outerR in +x).
+    //
+    // For v1 we go with: radial = projection of (dx, dy) onto the unit vector
+    // from centre toward the current cursor; tangential = remainder.
+    // Because we don't get the cursor position in this signature, fall back
+    // to: dx ↦ tangential rotation, dy ↦ radial pan. This matches the common
+    // "drag left/right rotates, drag up/down pans radius" mouse convention.
+    // A future enhancement can take the full (pointer, delta) pair via a
+    // richer `CoordPanArgs`.
+    void absCx;
+    void absCy;
+    const arc = arcSpan();
+    if (arc !== 0 && plotFrame.width > 0) {
+      const tangential = dx;
+      const rotation = direction * (tangential / plotFrame.width) * arc;
+      startAngle += rotation;
+      endAngle += rotation;
+    }
+    if (dy !== 0) {
+      // Translate the radius scale's domain. The radius scale corresponds to
+      // the *non-angle* viewport channel.
+      const radialAxis = angleChannel === "x" ? "y" : "x";
+      if (radialAxis === "y") viewport.panBy(0, dy);
+      else viewport.panBy(dy, 0);
+    }
+  }
+
+  function handleZoom(args: CoordZoomArgs): void {
+    const { factor, cx: ax, cy: ay, viewport } = args;
+    // Extract the relevant scalar component: bindDataViewport may issue
+    // per-axis factors (`{ x, y }`) after masking; collapse to the radial
+    // axis since angle scale stays put under zoom.
+    const radialAxis = angleChannel === "x" ? "y" : "x";
+    const fRadial: number =
+      typeof factor === "number" ? factor : radialAxis === "y" ? (factor.y ?? 1) : (factor.x ?? 1);
+    if (fRadial === 1) return;
+    if (radialAxis === "y") {
+      viewport.zoomAt(ax, ay, { y: fRadial });
+    } else {
+      viewport.zoomAt(ax, ay, { x: fRadial });
+    }
+  }
+
+  const coord: Coord & {
+    /** @internal — exposed for unit tests. Returns the current angular configuration. */
+    readonly __polar__: {
+      readonly startAngle: () => number;
+      readonly endAngle: () => number;
+      readonly innerRadius: () => number;
+      readonly outerRadius: () => number;
+      readonly angleChannel: "x" | "y";
+      readonly direction: 1 | -1;
+    };
+  } = {
+    kind: "polar",
+    bindFrame,
+    project,
+    segment,
+    renderAxes,
+    unproject,
+    handlePan,
+    handleZoom,
+    __polar__: {
+      startAngle: () => startAngle,
+      endAngle: () => endAngle,
+      innerRadius: () => innerRadius,
+      outerRadius: () => outerR,
+      angleChannel,
+      direction,
+    },
+  };
+  return coord;
+}
+
+/**
+ * Convenience polar coord: full circle, root at centre. Equivalent to
+ * `coordPolar({ openAngle: 0, innerRadius: 0 })`.
+ */
+export function coordRadial(
+  opts: Omit<CoordPolarOptions, "openAngle" | "innerRadius"> = {},
+): Coord {
+  return coordPolar({ ...opts, openAngle: 0, innerRadius: 0 });
+}
+
+/**
+ * Pin a coord to one plot frame (faceted panels). The facet loop mutates a
+ * SINGLE shared stateful coord via `bindFrame(panel.frame)` per panel; that's
+ * fine for the synchronous mark-push path (compiled right after the bind), but
+ * a geom's `hoverDecoration` closure captures `ctx.coord` and runs LATER (at
+ * hover, from the mount) — by then the shared coord is bound to the LAST
+ * panel's frame, so a polar halo would project against the wrong centre. This
+ * wrapper re-binds the underlying coord to THIS panel's frame before every
+ * frame-dependent delegate, so each panel's closures see a panel-stable
+ * projection. Cartesian's `bindFrame` is a no-op so this is zero-cost there.
+ */
+export function frameBoundCoord(coord: Coord, frame: import("insomni").Frame): Coord {
+  const rebind = <R>(fn: () => R): R => {
+    coord.bindFrame(frame);
+    return fn();
+  };
+  return {
+    kind: coord.kind,
+    bindFrame: () => coord.bindFrame(frame),
+    project: (p) => rebind(() => coord.project(p)),
+    segment: (p1, p2) => rebind(() => coord.segment(p1, p2)),
+    renderAxes: (a) => rebind(() => coord.renderAxes(a)),
+    unproject: (p) => rebind(() => coord.unproject(p)),
+    handlePan: (a) => coord.handlePan(a),
+    handleZoom: (a) => coord.handleZoom(a),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function scaleTickValues(
+  scale: ContinuousScale | TimeScale | BandScale<string>,
+  axisOpts?: { ticks?: unknown },
+): readonly unknown[] {
+  if ("bandwidth" in scale) {
+    return scale.ticks();
+  }
+  // Use the user-specified tick count when available; fall back to 8.
+  const userTicks = axisOpts?.ticks;
+  const count = typeof userTicks === "number" ? userTicks : 8;
+  return scale.ticks(count);
+}
+
+function pushLineAt(
+  layer: Layer,
+  origin: { x: number; y: number },
+  p0: Point,
+  p1: Point,
+  color: Color,
+  width: number,
+): void {
+  layer.pushLine({
+    x1: origin.x + p0.x,
+    y1: origin.y + p0.y,
+    x2: origin.x + p1.x,
+    y2: origin.y + p1.y,
+    color,
+    width,
+  });
+}
+
+function drawArc(
+  layer: Layer,
+  origin: { x: number; y: number },
+  cx: number,
+  cy: number,
+  r: number,
+  startAngle: number,
+  endAngle: number,
+  quality: number,
+  color: Color,
+  width: number,
+): void {
+  const arc = endAngle - startAngle;
+  const steps = Math.max(2, Math.ceil(Math.abs(arc) / quality));
+  let prevX = cx + r * Math.cos(startAngle);
+  let prevY = cy + r * Math.sin(startAngle);
+  for (let i = 1; i <= steps; i++) {
+    const t = i / steps;
+    const theta = startAngle + arc * t;
+    const x = cx + r * Math.cos(theta);
+    const y = cy + r * Math.sin(theta);
+    layer.pushLine({
+      x1: origin.x + prevX,
+      y1: origin.y + prevY,
+      x2: origin.x + x,
+      y2: origin.y + y,
+      color,
+      width,
+    });
+    prevX = x;
+    prevY = y;
+  }
+}

package/src/grammar/data/pivot.d.ts

@@ -0,0 +1,57 @@
+export interface FromMatrixOptions {
+    /** Y labels (rows). Top to bottom. Length must equal `values.length`. */
+    rows: readonly string[];
+    /** X labels (cols). Left to right. Length must equal `values[0].length`. */
+    cols: readonly string[];
+    /** Output key for the row label. Default `"row"`. */
+    rowKey?: string;
+    /** Output key for the col label. Default `"col"`. */
+    colKey?: string;
+    /** Output key for the cell value. Default `"value"`. */
+    valueKey?: string;
+}
+export type LongRow<R extends string, C extends string, V extends string> = {
+    [K in R | C | V]: K extends V ? number : string;
+};
+/**
+ * Convert a 2D `values[row][col]` matrix into long-format rows that the
+ * `tile()` geom consumes directly. Cells with `NaN` / `null` / `undefined`
+ * are kept (so consumers can opt into NA cell rendering); cells whose
+ * coordinates are out of range are skipped.
+ *
+ * Example:
+ * ```ts
+ * const long = fromMatrix(temperatures, {
+ *   rows: ["00:00", "06:00", "12:00", "18:00"],
+ *   cols: ["Mon", "Tue", "Wed", "Thu", "Fri"],
+ * });
+ * tile({ x: "col", y: "row", fill: "value" })
+ * ```
+ */
+export declare function fromMatrix(values: readonly (readonly number[])[], opts: FromMatrixOptions): {
+    row: string;
+    col: string;
+    value: number;
+}[];
+export interface PivotLongerOptions<T> {
+    /** Output column name for the original key. Default `"name"`. */
+    nameKey?: string;
+    /** Output column name for the value. Default `"value"`. */
+    valueKey?: string;
+    /** Optional id columns kept verbatim alongside the long pair. */
+    idColumns?: readonly (keyof T & string)[];
+}
+/**
+ * Pivot a wide row to a sequence of long rows — one per `keys` entry.
+ * `idColumns` are copied through to every output row so a per-row identifier
+ * (e.g. car name in the mtcars example) is preserved.
+ *
+ * Example:
+ * ```ts
+ * const long = pivotLonger(mtcars, ["mpg", "cyl", "disp", "hp"], {
+ *   idColumns: ["model"],
+ * });
+ * // → [{ model, name: "mpg", value }, { model, name: "cyl", value }, ...]
+ * ```
+ */
+export declare function pivotLonger<T extends Record<string, unknown>>(rows: readonly T[], keys: readonly (keyof T & string)[], options?: PivotLongerOptions<T>): Record<string, unknown>[];