@opendata-ai/openchart-engine 7.11.0 → 8.0.0-rc.10

package/src/charts/utils.ts

@@ -153,15 +153,17 @@ export function getColor(
 
 /**
  * Get color from a sequential (quantitative) color scale.
- * Maps a numeric value to a color via linear interpolation.
+ * Maps a numeric value to a color via linear interpolation, or to a discrete
+ * class color for binned (quantile/quantize/threshold) color scales.
  */
 export function getSequentialColor(
   scales: ResolvedScales,
   value: number,
   fallback: string = DEFAULT_COLOR,
 ): string | GradientDef {
-  if (scales.color?.type === 'sequential') {
-    const colorScale = scales.color.scale as unknown as (v: number) => string;
+  const type = scales.color?.type;
+  if (type === 'sequential' || type === 'quantile' || type === 'quantize' || type === 'threshold') {
+    const colorScale = scales.color!.scale as unknown as (v: number) => string;
     return colorScale(value);
   }
   return scales.defaultColor ?? fallback;

package/src/charts/waffle/__tests__/compute.test.ts

@@ -0,0 +1,305 @@
+import type { LayoutStrategy, Rect, RectMark } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+
+import { compileChart } from '../../../compile';
+import type { NormalizedChartSpec } from '../../../compiler/types';
+import { computeScales } from '../../../layout/scales';
+import { computeWaffleMarks, largestRemainderCells } from '../compute';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+const chartArea: Rect = { x: 40, y: 20, width: 400, height: 400 };
+
+const fullStrategy: LayoutStrategy = {
+  labelMode: 'all',
+  legendPosition: 'right',
+  annotationPosition: 'inline',
+  axisLabelDensity: 'full',
+};
+
+const energyMix = [
+  { source: 'Fossil', share: 60 },
+  { source: 'Renewables', share: 30 },
+  { source: 'Nuclear', share: 10 },
+];
+
+function makeWaffleSpec(overrides: Partial<NormalizedChartSpec> = {}): NormalizedChartSpec {
+  return {
+    markType: 'waffle',
+    markDef: { type: 'waffle' },
+    data: [...energyMix],
+    encoding: {
+      y: { field: 'share', type: 'quantitative' },
+      color: { field: 'source', type: 'nominal' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+    ...overrides,
+  } as NormalizedChartSpec;
+}
+
+function marksFor(spec: NormalizedChartSpec): RectMark[] {
+  const scales = computeScales(spec, chartArea, spec.data);
+  return computeWaffleMarks(spec, scales, chartArea, fullStrategy);
+}
+
+/** Deterministic LCG so the property test carries no runtime randomness. */
+function lcg(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    s = (s * 1664525 + 1013904223) >>> 0;
+    return s / 2 ** 32;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// largestRemainderCells
+// ---------------------------------------------------------------------------
+
+describe('largestRemainderCells', () => {
+  it('sums exactly to units', () => {
+    expect(largestRemainderCells([60, 30, 10], 100).reduce((a, b) => a + b, 0)).toBe(100);
+    expect(largestRemainderCells([1, 1, 1], 100).reduce((a, b) => a + b, 0)).toBe(100);
+    expect(largestRemainderCells([7, 13, 3], 40).reduce((a, b) => a + b, 0)).toBe(40);
+  });
+
+  it('rounds a 0.4-cell category by largest remainder while the total stays exact', () => {
+    // Quotas 33.2 / 33.2 / 33.2 / 0.4: the 0.4 remainder is the largest, so
+    // the small category wins the single leftover cell.
+    expect(largestRemainderCells([33.2, 33.2, 33.2, 0.4], 100)).toEqual([33, 33, 33, 1]);
+
+    // Quotas 49.8 / 49.8 / 0.4: both 0.8 remainders beat 0.4, so the small
+    // category legitimately rounds to 0 cells (no minimum-1-cell rule).
+    expect(largestRemainderCells([49.8, 49.8, 0.4], 100)).toEqual([50, 50, 0]);
+  });
+
+  it('breaks equal remainders by larger raw value, then stable input index', () => {
+    // Quotas 1.5 / 2.5 / 3.5 / 2.5 (all remainders 0.5), two leftover cells:
+    // the largest raw value (35) wins first, then the 25s tie and the earlier
+    // input index (1) wins over index 3.
+    expect(largestRemainderCells([15, 25, 35, 25], 10)).toEqual([1, 3, 4, 2]);
+
+    // Fully symmetric tie: value tiebreak is moot, index order decides.
+    expect(largestRemainderCells([25, 25, 25, 25], 10)).toEqual([3, 3, 2, 2]);
+  });
+
+  it('allocates 0 cells to non-finite and negative values', () => {
+    expect(largestRemainderCells([Number.NaN, 50, -10, 50], 10)).toEqual([0, 5, 0, 5]);
+  });
+
+  it('returns all zeros when there is nothing to allocate', () => {
+    expect(largestRemainderCells([0, 0], 100)).toEqual([0, 0]);
+    expect(largestRemainderCells([], 100)).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// computeWaffleMarks geometry
+// ---------------------------------------------------------------------------
+
+describe('computeWaffleMarks', () => {
+  it('emits square cells with a gap of cell/6', () => {
+    const marks = marksFor(makeWaffleSpec());
+    expect(marks).toHaveLength(100);
+
+    const first = marks[0];
+    expect(first.width).toBeCloseTo(first.height);
+
+    // Neighbor in the same row sits one cell + gap to the right.
+    const second = marks[1];
+    expect(second.y).toBe(first.y);
+    expect(second.x - (first.x + first.width)).toBeCloseTo(first.width / 6);
+  });
+
+  it('fills bottom-left to top-right by rows', () => {
+    const marks = marksFor(makeWaffleSpec());
+
+    // First cell is the leftmost column; the first 10 cells share the bottom row.
+    const xs = marks.map((m) => m.x);
+    const ys = marks.map((m) => m.y);
+    expect(marks[0].x).toBe(Math.min(...xs));
+    expect(marks[0].y).toBe(Math.max(...ys));
+    for (let i = 1; i < 10; i++) {
+      expect(marks[i].y).toBe(marks[0].y);
+      expect(marks[i].x).toBeGreaterThan(marks[i - 1].x);
+    }
+    // Cell 10 wraps to the next row up.
+    expect(marks[10].x).toBe(marks[0].x);
+    expect(marks[10].y).toBeLessThan(marks[0].y);
+    // Last cell tops out the grid.
+    expect(marks[99].y).toBe(Math.min(...ys));
+  });
+
+  it('centers the grid in the chart area', () => {
+    const marks = marksFor(makeWaffleSpec());
+    const minX = Math.min(...marks.map((m) => m.x));
+    const maxX = Math.max(...marks.map((m) => m.x + m.width));
+    const minY = Math.min(...marks.map((m) => m.y));
+    const maxY = Math.max(...marks.map((m) => m.y + m.height));
+
+    expect(minX - chartArea.x).toBeCloseTo(chartArea.x + chartArea.width - maxX);
+    expect(minY - chartArea.y).toBeCloseTo(chartArea.y + chartArea.height - maxY);
+  });
+
+  it('assigns category cells contiguously in data order with stable keys', () => {
+    const marks = marksFor(makeWaffleSpec());
+
+    const bySource = (s: string) =>
+      marks.filter((m) => (m.data as { source: string }).source === s);
+    expect(bySource('Fossil')).toHaveLength(60);
+    expect(bySource('Renewables')).toHaveLength(30);
+    expect(bySource('Nuclear')).toHaveLength(10);
+
+    expect(marks[0].key).toBe('Fossil|0');
+    expect(marks[59].key).toBe('Fossil|59');
+    expect(marks[60].key).toBe('Renewables|0');
+    expect(marks[99].key).toBe('Nuclear|9');
+  });
+
+  it('respects units and columns mark options', () => {
+    const spec = makeWaffleSpec({
+      markDef: { type: 'waffle', units: 40, columns: 8 },
+    });
+    const marks = marksFor(spec);
+    expect(marks).toHaveLength(40);
+
+    // 8 columns x 5 rows: cells 0-7 share the bottom row, cell 8 wraps.
+    expect(marks[7].y).toBe(marks[0].y);
+    expect(marks[8].x).toBe(marks[0].x);
+    expect(marks[8].y).toBeLessThan(marks[0].y);
+  });
+
+  it('labels the first cell of each category "x of N units" and marks the rest decorative', () => {
+    const marks = marksFor(makeWaffleSpec());
+
+    expect(marks[0].aria.label).toBe('Fossil: 60 of 100 units (60%)');
+    expect(marks[0].aria.decorative).toBeUndefined();
+    expect(marks[1].aria.label).toBe('Fossil: 60 of 100 units (60%)');
+    expect(marks[1].aria.decorative).toBe(true);
+    expect(marks[60].aria.label).toBe('Renewables: 30 of 100 units (30%)');
+    expect(marks[60].aria.decorative).toBeUndefined();
+  });
+
+  it('defaults cornerRadius to 1 and honors a mark-level override', () => {
+    expect(marksFor(makeWaffleSpec())[0].cornerRadius).toBe(1);
+
+    const spec = makeWaffleSpec({ markDef: { type: 'waffle', cornerRadius: 3 } });
+    expect(marksFor(spec)[0].cornerRadius).toBe(3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// compileChart integration (spec in, layout out)
+// ---------------------------------------------------------------------------
+
+describe('compileChart with waffle marks', () => {
+  const baseSpec = {
+    mark: 'waffle' as const,
+    data: [...energyMix],
+    encoding: {
+      theta: { field: 'share', type: 'quantitative' as const },
+      color: { field: 'source', type: 'nominal' as const },
+    },
+  };
+
+  it('renders exactly units cells for random distributions summing to 100% (property test)', () => {
+    const rand = lcg(20260711);
+
+    for (let trial = 0; trial < 25; trial++) {
+      const categoryCount = 2 + Math.floor(rand() * 7);
+      const raw = Array.from({ length: categoryCount }, () => 0.01 + rand());
+      const total = raw.reduce((a, b) => a + b, 0);
+      const data = raw.map((v, i) => ({ category: `C${i}`, share: (v / total) * 100 }));
+
+      const layout = compileChart(
+        {
+          mark: 'waffle',
+          data,
+          encoding: {
+            theta: { field: 'share', type: 'quantitative' },
+            color: { field: 'category', type: 'nominal' },
+          },
+        },
+        { width: 600, height: 400 },
+      );
+
+      const cells = layout.marks.filter((m) => m.type === 'rect');
+      expect(cells).toHaveLength(100);
+    }
+  });
+
+  it('accepts theta as the value channel and compiles without axes or gridlines', () => {
+    const layout = compileChart(baseSpec, { width: 600, height: 400 });
+
+    expect(layout.marks.filter((m) => m.type === 'rect')).toHaveLength(100);
+    expect(layout.axes.x).toBeUndefined();
+    expect(layout.axes.y).toBeUndefined();
+  });
+
+  it('shares one tooltip object across every cell of a category', () => {
+    const layout = compileChart(baseSpec, { width: 600, height: 400 });
+
+    const rects = layout.marks
+      .map((m, i) => ({ mark: m as RectMark, id: `rect-${i}` }))
+      .filter(({ mark }) => mark.type === 'rect');
+
+    const fossilIds = rects
+      .filter(({ mark }) => (mark.data as { source: string }).source === 'Fossil')
+      .map(({ id }) => id);
+    const nuclearIds = rects
+      .filter(({ mark }) => (mark.data as { source: string }).source === 'Nuclear')
+      .map(({ id }) => id);
+    expect(fossilIds).toHaveLength(60);
+
+    const fossilTooltip = layout.tooltipDescriptors.get(fossilIds[0]);
+    expect(fossilTooltip).toBeDefined();
+    // Literally the same object for all cells: one hover target per category.
+    for (const id of fossilIds) {
+      expect(layout.tooltipDescriptors.get(id)).toBe(fossilTooltip);
+    }
+    expect(layout.tooltipDescriptors.get(nuclearIds[0])).not.toBe(fossilTooltip);
+
+    expect(fossilTooltip!.title).toBe('Fossil');
+    const share = fossilTooltip!.fields.find((f) => f.label === 'Share');
+    expect(share?.value).toBe('60 of 100 units');
+  });
+
+  it('lists a category in the legend even when it rounds to 0 cells', () => {
+    const layout = compileChart(
+      {
+        mark: 'waffle',
+        data: [
+          { source: 'A', share: 49.8 },
+          { source: 'B', share: 49.8 },
+          { source: 'C', share: 0.4 },
+        ],
+        encoding: {
+          theta: { field: 'share', type: 'quantitative' },
+          color: { field: 'source', type: 'nominal' },
+        },
+      },
+      { width: 600, height: 400 },
+    );
+
+    const cells = layout.marks.filter((m): m is RectMark => m.type === 'rect');
+    expect(cells).toHaveLength(100);
+    expect(cells.some((m) => (m.data as { source: string }).source === 'C')).toBe(false);
+
+    expect(layout.legend.type).toBe('categorical');
+    const labels =
+      layout.legend.type === 'categorical' ? layout.legend.entries.map((e) => e.label) : [];
+    expect(labels).toContain('C');
+  });
+
+  it('generates alt text with the unit framing', () => {
+    const layout = compileChart(baseSpec, { width: 600, height: 400 });
+    expect(layout.a11y.altText).toContain('Waffle chart');
+    expect(layout.a11y.altText).toContain('dividing 100 units');
+  });
+});

package/src/charts/waffle/compute.ts

@@ -0,0 +1,197 @@
+/**
+ * Waffle chart mark computation.
+ *
+ * A unit grid ("3 in 100 people") for part-to-whole counts. Category values
+ * aggregate by the nominal color field, normalize to `markDef.units` cells
+ * via largest-remainder rounding (cells always sum exactly to units), and
+ * fill the grid bottom-left to top-right by rows, matching how readers count.
+ *
+ * Geometry: square cells with a gap of cell/6, grid centered in the chart
+ * area. No positional scales are consumed; the value comes straight from the
+ * data (the `theta` channel aliases to `y` in the sugar pass, same as arc).
+ *
+ * Zero-cell categories are legitimate: a nonzero share can round to 0 cells
+ * and there is deliberately no minimum-1-cell rule (a floor would distort the
+ * other categories). The legend still lists the category because legend
+ * entries derive from data, not marks.
+ */
+
+import type {
+  DataRow,
+  Encoding,
+  LayoutStrategy,
+  MarkAria,
+  Rect,
+  RectMark,
+} from '@opendata-ai/openchart-core';
+import { formatPercent } from '@opendata-ai/openchart-core';
+
+import { serializeKeyValue } from '../../compiler/keys';
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+import { getColor } from '../utils';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default total cell count (the "out of 100" framing). */
+const DEFAULT_UNITS = 100;
+
+/** Default column count (10x10 grid at the default units). */
+const DEFAULT_COLUMNS = 10;
+
+/** Default cell corner radius (px). Subtle rounding; cells stay data-crisp. */
+const DEFAULT_CORNER_RADIUS = 1;
+
+/** Gap between cells as a fraction of the cell size. */
+const GAP_FRACTION = 1 / 6;
+
+// ---------------------------------------------------------------------------
+// Largest-remainder rounding
+// ---------------------------------------------------------------------------
+
+/**
+ * Allocate `units` integer cells across `values` proportionally using the
+ * largest-remainder method, so the result always sums exactly to `units`.
+ *
+ * Tiebreak is deterministic and never depends on map iteration order:
+ * equal remainders break by larger raw value, then by stable input index.
+ * Non-finite and negative values allocate 0 cells.
+ */
+export function largestRemainderCells(values: number[], units: number): number[] {
+  const clean = values.map((v) => (Number.isFinite(v) && v > 0 ? v : 0));
+  const total = clean.reduce((sum, v) => sum + v, 0);
+  const cells = new Array<number>(values.length).fill(0);
+  if (total <= 0 || units <= 0) return cells;
+
+  const quotas = clean.map((v) => (v / total) * units);
+  let allocated = 0;
+  for (let i = 0; i < quotas.length; i++) {
+    cells[i] = Math.floor(quotas[i]);
+    allocated += cells[i];
+  }
+
+  // Distribute the leftover cells to the largest remainders. Ties break by
+  // larger raw value, then smaller input index (stable and deterministic).
+  const order = quotas
+    .map((q, i) => ({ remainder: q - Math.floor(q), value: clean[i], index: i }))
+    .sort((a, b) => b.remainder - a.remainder || b.value - a.value || a.index - b.index);
+  for (let k = 0; k < units - allocated; k++) {
+    cells[order[k].index] += 1;
+  }
+
+  return cells;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute waffle cell marks from a normalized chart spec.
+ *
+ * Categories come from the color field (aggregated in data order, matching
+ * pie), the share value from the quantitative y channel (theta pre-aliased
+ * to y). Emits one RectMark per cell in fill order (bottom-left to top-right
+ * by rows), which also drives the entrance-stagger sweep.
+ */
+export function computeWaffleMarks(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  chartArea: Rect,
+  _strategy: LayoutStrategy,
+): RectMark[] {
+  const encoding = spec.encoding as Encoding;
+
+  const valueChannel = encoding.y ?? encoding.x;
+  const colorField = encoding.color && 'field' in encoding.color ? encoding.color.field : undefined;
+  if (!valueChannel || !colorField) return [];
+
+  // Aggregate values by category, preserving data order (drives cell order,
+  // color assignment, and the legend, which derives the same order from data).
+  const categoryTotals = new Map<string, number>();
+  const categoryRows = new Map<string, DataRow>();
+  for (const row of spec.data) {
+    const cat = String(row[colorField] ?? '');
+    const val = Number(row[valueChannel.field] ?? 0);
+    if (!Number.isFinite(val) || val < 0) continue;
+
+    categoryTotals.set(cat, (categoryTotals.get(cat) ?? 0) + val);
+    if (!categoryRows.has(cat)) {
+      categoryRows.set(cat, row);
+    }
+  }
+
+  const categories = [...categoryTotals.keys()];
+  const values = categories.map((cat) => categoryTotals.get(cat)!);
+  const total = values.reduce((sum, v) => sum + v, 0);
+  if (categories.length === 0 || total <= 0) return [];
+
+  const units = Math.max(1, Math.round(spec.markDef.units ?? DEFAULT_UNITS));
+  const columns = Math.max(1, Math.round(spec.markDef.columns ?? DEFAULT_COLUMNS));
+  const rows = Math.ceil(units / columns);
+
+  const cellCounts = largestRemainderCells(values, units);
+
+  // Square cells with gap = cell/6: grid width = columns*cell + (columns-1)*gap.
+  // Solve for the cell size on both axes and take the smaller so the grid
+  // stays square and inside the chart area, then center it.
+  const cell = Math.min(
+    chartArea.width / (columns + (columns - 1) * GAP_FRACTION),
+    chartArea.height / (rows + (rows - 1) * GAP_FRACTION),
+  );
+  if (!(cell > 0)) return [];
+
+  const gap = cell * GAP_FRACTION;
+  const step = cell + gap;
+  const gridWidth = columns * cell + (columns - 1) * gap;
+  const gridHeight = rows * cell + (rows - 1) * gap;
+  const originX = chartArea.x + (chartArea.width - gridWidth) / 2;
+  // Top edge of the bottom row; rows fill upward from here.
+  const bottomRowY = chartArea.y + (chartArea.height - gridHeight) / 2 + gridHeight - cell;
+
+  const cornerRadius =
+    spec.markDef.cornerRadius === 'pill'
+      ? cell / 2
+      : (spec.markDef.cornerRadius ?? DEFAULT_CORNER_RADIUS);
+
+  const marks: RectMark[] = [];
+  let cellIndex = 0;
+
+  for (let c = 0; c < categories.length; c++) {
+    const category = categories[c];
+    const count = cellCounts[c];
+    const value = categoryTotals.get(category)!;
+    const percentStr = total > 0 ? formatPercent(value / total) : '0%';
+    const row = categoryRows.get(category)!;
+    const catKey = serializeKeyValue(category);
+    const fill = getColor(scales, category);
+
+    // One SR stop per category: the first cell carries the label, the rest
+    // are decorative duplicates (100 cells would drown screen reader users).
+    const aria: MarkAria = {
+      label: `${category}: ${count} of ${units} units (${percentStr})`,
+    };
+
+    for (let k = 0; k < count; k++, cellIndex++) {
+      const col = cellIndex % columns;
+      const gridRow = Math.floor(cellIndex / columns); // 0 = bottom row
+
+      marks.push({
+        type: 'rect',
+        key: `${catKey}|${k}`,
+        x: originX + col * step,
+        y: bottomRowY - gridRow * step,
+        width: cell,
+        height: cell,
+        fill,
+        cornerRadius,
+        data: row as Record<string, unknown>,
+        aria: k === 0 ? aria : { ...aria, decorative: true },
+      });
+    }
+  }
+
+  return marks;
+}

package/src/charts/waffle/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Waffle chart module.
+ *
+ * Exports the waffle renderer and computation functions. Waffles emit plain
+ * RectMark[] (rendered by the existing rect mark path) with no per-cell value
+ * labels: the legend names the categories and the tooltip carries the counts,
+ * so cell labels would only add noise to the grid.
+ */
+
+import type { Mark } from '@opendata-ai/openchart-core';
+import type { ChartRenderer } from '../registry';
+import { computeWaffleMarks } from './compute';
+
+// ---------------------------------------------------------------------------
+// Waffle chart renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Waffle chart renderer.
+ *
+ * Produces one square cell per unit, filled bottom-left to top-right by rows.
+ */
+export const waffleRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _theme) => {
+  return computeWaffleMarks(spec, scales, chartArea, strategy) as Mark[];
+};
+
+// ---------------------------------------------------------------------------
+// Public exports
+// ---------------------------------------------------------------------------
+
+export { computeWaffleMarks, largestRemainderCells } from './compute';

package/src/compile/__tests__/color-scale-reverse.test.ts

@@ -0,0 +1,89 @@
+import { DIVERGING_PALETTES } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { compileChart } from '../../compile';
+
+const OPTIONS = { width: 800, height: 400 };
+
+/** d3 hands interpolated colors back as `rgb(r, g, b)`; compare on a single form. */
+function hex(value: string): string {
+  const rgb = /^rgb\((\d+),\s*(\d+),\s*(\d+)\)$/.exec(value.trim());
+  if (!rgb) return value.trim().toLowerCase();
+  const channel = (n: string) => Number(n).toString(16).padStart(2, '0');
+  return `#${channel(rgb[1])}${channel(rgb[2])}${channel(rgb[3])}`;
+}
+
+const ROWS = [
+  { day: 'a', value: -2 },
+  { day: 'b', value: 0 },
+  { day: 'c', value: 2 },
+];
+
+/** The compiled fill of the mark carrying `value`, as the reader would see it. */
+function colorAt(layout: ReturnType<typeof compileChart>, value: number): string {
+  const mark = layout.marks.find(
+    (m) => (m as { data?: Record<string, unknown> }).data?.value === value,
+  );
+  const fill = (mark as { fill?: string } | undefined)?.fill;
+  return hex(String(fill));
+}
+
+const RED_BLUE = DIVERGING_PALETTES.redBlue;
+const RED = hex(RED_BLUE[0]);
+const BLUE = hex(RED_BLUE[RED_BLUE.length - 1]);
+
+// A bar, not a rect: this suite is about the color ramp, and it needs a mark
+// with a quantitative axis to carry the value. `rect` used to alias the column
+// renderer, so it stood in for one here; now that `rect` is a real heatmap mark
+// (two categorical axes, cells sized by bandwidth) it emits nothing for a
+// quantitative y, and there is no fill to read back.
+function spec(reverse?: boolean) {
+  return {
+    mark: 'bar' as const,
+    data: ROWS,
+    encoding: {
+      x: { field: 'day', type: 'nominal' as const },
+      y: { field: 'value', type: 'quantitative' as const },
+      color: {
+        field: 'value',
+        type: 'quantitative' as const,
+        scale: reverse ? { scheme: 'redBlue', reverse: true } : { scheme: 'redBlue' },
+      },
+    },
+  };
+}
+
+describe('scale.reverse on a color channel', () => {
+  it('ramps low -> red, high -> blue by default (ColorBrewer RdBu order)', () => {
+    const layout = compileChart(spec(), OPTIONS);
+    expect(colorAt(layout, -2)).toBe(RED);
+    expect(colorAt(layout, 2)).toBe(BLUE);
+  });
+
+  it('flips the ramp so low -> blue, high -> red', () => {
+    const layout = compileChart(spec(true), OPTIONS);
+    expect(colorAt(layout, -2)).toBe(BLUE);
+    expect(colorAt(layout, 2)).toBe(RED);
+  });
+
+  it('keeps the diverging midpoint label when the ramp is reversed', () => {
+    // A reversed diverging ramp is still diverging: flipping the stops must not
+    // cost it the center tick (min / mid / max, not just min / max).
+    const forward = compileChart(spec(), OPTIONS).legend;
+    const reversed = compileChart(spec(true), OPTIONS).legend;
+    const tickCount = (l: typeof forward) =>
+      (l as { ticks?: unknown[] } | undefined)?.ticks?.length ?? 0;
+    expect(tickCount(forward)).toBe(3);
+    expect(tickCount(reversed)).toBe(tickCount(forward));
+  });
+
+  it('keeps the legend ramp in step with the marks', () => {
+    const legend = compileChart(spec(true), OPTIONS).legend;
+    // The legend resolves its ramp from the same scale.range the marks use, so a
+    // reversed scale must not leave the legend pointing the original direction.
+    expect(legend?.type).toBe('continuous');
+    const stops = (legend as { colorStops: Array<{ color: string }> }).colorStops;
+    expect(stops.length).toBeGreaterThan(1);
+    expect(hex(stops[0].color)).toBe(BLUE);
+    expect(hex(stops[stops.length - 1].color)).toBe(RED);
+  });
+});