@opendata-ai/openchart-engine 8.0.0-rc.12 → 8.0.0-rc.3

package/src/charts/rect/index.ts

@@ -0,0 +1,127 @@
+/**
+ * Rect mark renderer (heatmap cells).
+ *
+ * The Vega-Lite `rect` mark: one cell per row, positioned by x and y, colored
+ * by the `color` channel. The canonical use is a two-way heatmap (nominal x
+ * nominal, quantitative color), which is what this renderer is built for.
+ *
+ * `rect` used to alias `columnRenderer`, which hard-requires a band x-scale and
+ * a *linear* y-scale (it anchors every cell to `yScale(0)`). A heatmap has a
+ * band scale on both axes, so `columnRenderer` bailed at its bandwidth guard and
+ * emitted nothing: `mark: 'rect'` rendered a blank chart, with no error.
+ *
+ * Not to be confused with `RectMark`, the layout primitive that columns, waffle
+ * cells, calendar cells, and dot stems all emit. That was never broken; only the
+ * spec-level `mark: 'rect'` was.
+ */
+
+import type { Encoding, Mark, MarkAria, Rect, RectMark } from '@opendata-ai/openchart-core';
+import { formatNumber } from '@opendata-ai/openchart-core';
+import type { ScaleBand } from 'd3-scale';
+
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+import type { ChartRenderer } from '../registry';
+import { getColor, getSequentialColor, scaleValue } from '../utils';
+
+/**
+ * Cell extent along one axis. `resolveScale` gives `rect` a band scale on both
+ * axes (see the `chartType === 'rect'` branch in layout/scales.ts), so the
+ * bandwidth *is* the cell size. A non-band scale means a quantitative axis,
+ * which would need binning to have a cell width at all: return 0 so the caller
+ * can bail rather than emit degenerate zero-area cells.
+ */
+function bandwidthOf(scale: ResolvedScales['x']): number {
+  const band = scale?.scale as Partial<ScaleBand<string>> | undefined;
+  return typeof band?.bandwidth === 'function' ? band.bandwidth() : 0;
+}
+
+/**
+ * Compute rect (heatmap cell) marks from a normalized spec and resolved scales.
+ *
+ * Both axes are band scales, so a cell's x/y is the scaled value directly (a
+ * band places the cell's leading corner there) and its size is the bandwidth.
+ */
+export function computeRectMarks(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  _chartArea: Rect,
+): RectMark[] {
+  const encoding = spec.encoding as Encoding;
+  const xChannel = encoding.x;
+  const yChannel = encoding.y;
+
+  if (!xChannel || !yChannel || !scales.x || !scales.y) return [];
+
+  const colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
+  const isSequential = colorEnc?.type === 'quantitative';
+
+  const cellWidth = bandwidthOf(scales.x);
+  const cellHeight = bandwidthOf(scales.y);
+  // A quantitative axis yields no bandwidth. Cells would be zero-area and
+  // invisible, so emit nothing rather than pretend: `rect` wants two
+  // categorical axes (bin the field first to heatmap a continuous one).
+  if (cellWidth <= 0 || cellHeight <= 0) return [];
+
+  const marks: RectMark[] = [];
+
+  for (const row of spec.data) {
+    const xVal = scaleValue(scales.x.scale, scales.x.type, row[xChannel.field]);
+    const yVal = scaleValue(scales.y.scale, scales.y.type, row[yChannel.field]);
+    if (xVal == null || yVal == null) continue;
+
+    // A quantitative color channel drives a sequential/binned ramp (the heatmap
+    // case); a nominal one picks a categorical swatch.
+    let fill: RectMark['fill'];
+    if (colorEnc && isSequential) {
+      const value = Number(row[colorEnc.field]);
+      if (!Number.isFinite(value)) continue;
+      fill = getSequentialColor(scales, value);
+    } else if (colorEnc) {
+      fill = getColor(scales, String(row[colorEnc.field] ?? '__default__'));
+    } else {
+      fill = getColor(scales, '__default__');
+    }
+
+    const colorValue = colorEnc ? row[colorEnc.field] : undefined;
+    const colorLabel =
+      colorEnc && colorValue != null
+        ? `, ${colorEnc.field}: ${
+            typeof colorValue === 'number' ? formatNumber(colorValue) : String(colorValue)
+          }`
+        : '';
+    const aria: MarkAria = {
+      label: `${row[xChannel.field]}, ${row[yChannel.field]}${colorLabel}`,
+    };
+
+    marks.push({
+      type: 'rect',
+      x: xVal,
+      y: yVal,
+      width: cellWidth,
+      height: cellHeight,
+      fill,
+      data: row as Record<string, unknown>,
+      aria,
+    });
+  }
+
+  // Key on the cell's coordinates: the x/y pair is what identifies a cell across
+  // a data update, which is what the transition driver matches on.
+  const rawKeys = marks.map(
+    (m) =>
+      `${serializeKeyValue(m.data[xChannel.field])}|${serializeKeyValue(m.data[yChannel.field])}`,
+  );
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < marks.length; i++) {
+    marks[i].key = keys[i];
+  }
+
+  return marks;
+}
+
+/** Rect (heatmap) chart renderer. */
+export const rectRenderer: ChartRenderer = (spec, scales, chartArea, _strategy, _theme) => {
+  return computeRectMarks(spec, scales, chartArea) as Mark[];
+};

package/src/charts/registry.ts

@@ -0,0 +1,72 @@
+/**
+ * Chart renderer registry.
+ *
+ * Each chart type (line, bar, column, scatter, pie, donut, dot) registers
+ * a renderer that produces marks from normalized specs and resolved scales.
+ * The registry pattern decouples chart-type logic from the compile pipeline.
+ */
+
+import type { LayoutStrategy, Mark, Rect, ResolvedTheme } from '@opendata-ai/openchart-core';
+
+import type { NormalizedChartSpec } from '../compiler/types';
+import type { ResolvedScales } from '../layout/scales';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A chart renderer function.
+ *
+ * Takes a normalized spec, resolved scales, chart area, layout strategy,
+ * the resolved theme for theme-aware styling (e.g. label colors), and the
+ * full container width (used by geometry gates that must key off the
+ * container, not the derived plot width). Returns an array of marks to render.
+ */
+export type ChartRenderer = (
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  chartArea: Rect,
+  strategy: LayoutStrategy,
+  theme: ResolvedTheme,
+  containerWidth: number,
+) => Mark[];
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+const renderers = new Map<string, ChartRenderer>();
+
+/**
+ * Register a chart renderer for a specific chart type.
+ *
+ * @param type - Chart type string (e.g. "line", "bar").
+ * @param renderer - The renderer function.
+ */
+export function registerChartRenderer(type: string, renderer: ChartRenderer): void {
+  renderers.set(type, renderer);
+}
+
+/**
+ * Get the registered chart renderer for a type.
+ *
+ * @param type - Chart type string.
+ * @returns The renderer, or undefined if no renderer is registered.
+ */
+export function getChartRenderer(type: string): ChartRenderer | undefined {
+  return renderers.get(type);
+}
+
+/**
+ * Clear all registered renderers. Useful for testing.
+ *
+ * Note: the built-in renderers (line, bar, column, ...) register as a
+ * side-effect of importing `./builtin`. Once cleared, they do not come
+ * back on their own — subsequent `compileChart(...)` calls will return
+ * empty marks. Tests that call `clearRenderers()` should follow up with
+ * `registerBuiltinRenderers()` from `./builtin` to restore the defaults.
+ */
+export function clearRenderers(): void {
+  renderers.clear();
+}

package/src/charts/rule/index.ts

@@ -0,0 +1,139 @@
+/**
+ * Rule mark renderer.
+ *
+ * Computes RuleMarkLayout marks from a normalized chart spec.
+ * Rules are line segments, typically used for reference lines as data marks.
+ * Supports x, y, x2, y2 encoding channels for start/end positioning.
+ */
+
+import type { Encoding, Mark, MarkAria, Rect, RuleMarkLayout } from '@opendata-ai/openchart-core';
+import { getRepresentativeColor } from '@opendata-ai/openchart-core';
+
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+import type { ChartRenderer } from '../registry';
+import { getColor, scaleValue } from '../utils';
+
+/**
+ * Compute rule marks from spec data and resolved scales.
+ *
+ * Positioning logic:
+ * - x only: vertical line spanning full chart height
+ * - y only: horizontal line spanning full chart width
+ * - x + x2: horizontal segment at the y position (or spanning full height)
+ * - y + y2: vertical segment at the x position (or spanning full width)
+ * - x + y + x2 + y2: arbitrary line segment
+ */
+export function computeRuleMarks(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  chartArea: Rect,
+): RuleMarkLayout[] {
+  const encoding = spec.encoding as Encoding;
+  const xChannel = encoding.x;
+  const yChannel = encoding.y;
+  const x2Channel = encoding.x2;
+  const y2Channel = encoding.y2;
+  const colorEncoding = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
+  const colorField = colorEncoding?.field;
+
+  const marks: RuleMarkLayout[] = [];
+
+  for (const row of spec.data) {
+    let x1 = chartArea.x;
+    let y1 = chartArea.y;
+    let x2 = chartArea.x + chartArea.width;
+    let y2 = chartArea.y + chartArea.height;
+
+    // Resolve x position
+    if (xChannel && scales.x) {
+      const xVal = scaleValue(scales.x.scale, scales.x.type, row[xChannel.field]);
+      if (xVal == null) continue;
+      x1 = xVal;
+      x2 = xVal; // default: vertical line (same x)
+    }
+
+    // Resolve y position
+    if (yChannel && scales.y) {
+      const yVal = scaleValue(scales.y.scale, scales.y.type, row[yChannel.field]);
+      if (yVal == null) continue;
+      y1 = yVal;
+      y2 = yVal; // default: horizontal line (same y)
+    }
+
+    // If x is set but not y, span full height (vertical line)
+    if (xChannel && !yChannel) {
+      y1 = chartArea.y;
+      y2 = chartArea.y + chartArea.height;
+    }
+
+    // If y is set but not x, span full width (horizontal line)
+    if (yChannel && !xChannel) {
+      x1 = chartArea.x;
+      x2 = chartArea.x + chartArea.width;
+    }
+
+    // Resolve x2 if present
+    if (x2Channel && scales.x) {
+      const x2Val = scaleValue(scales.x.scale, scales.x.type, row[x2Channel.field]);
+      if (x2Val != null) x2 = x2Val;
+    }
+
+    // Resolve y2 if present
+    if (y2Channel && scales.y) {
+      const y2Val = scaleValue(scales.y.scale, scales.y.type, row[y2Channel.field]);
+      if (y2Val != null) y2 = y2Val;
+    }
+
+    const color = getRepresentativeColor(
+      colorField
+        ? getColor(scales, String(row[colorField] ?? '__default__'))
+        : getColor(scales, '__default__'),
+    );
+
+    const strokeDashEncoding =
+      encoding.strokeDash && 'field' in encoding.strokeDash ? encoding.strokeDash : undefined;
+    const strokeDasharray = strokeDashEncoding
+      ? String(row[strokeDashEncoding.field] ?? '')
+      : undefined;
+
+    const aria: MarkAria = {
+      label: `Rule from (${Math.round(x1)}, ${Math.round(y1)}) to (${Math.round(x2)}, ${Math.round(y2)})`,
+    };
+
+    marks.push({
+      type: 'rule',
+      x1,
+      y1,
+      x2,
+      y2,
+      stroke: color,
+      strokeWidth: 1,
+      strokeDasharray: strokeDasharray || undefined,
+      opacity:
+        encoding.opacity && 'field' in encoding.opacity
+          ? Math.max(0, Math.min(1, Number(row[encoding.opacity.field]) || 1))
+          : undefined,
+      data: row as Record<string, unknown>,
+      aria,
+    });
+  }
+
+  // Stamp keys: position-defining values, fall back to index
+  const posField = xChannel?.field ?? yChannel?.field;
+  const rawKeys = marks.map((m, i) => (posField ? serializeKeyValue(m.data[posField]) : String(i)));
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < marks.length; i++) {
+    marks[i].key = keys[i];
+  }
+
+  return marks;
+}
+
+/**
+ * Rule chart renderer.
+ */
+export const ruleRenderer: ChartRenderer = (spec, scales, chartArea, _strategy, _theme) => {
+  return computeRuleMarks(spec, scales, chartArea) as Mark[];
+};