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

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);
+  });
+});

package/src/compile/__tests__/data-clip.test.ts

@@ -0,0 +1,127 @@
+import type { Encoding } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { filterClippedDomains } from '../data-clip';
+
+describe('filterClippedDomains', () => {
+  const data = [
+    { x: -5, y: 10 },
+    { x: 10, y: 20 },
+    { x: 25, y: 80 },
+    { x: 50, y: 110 },
+    { x: 80, y: 200 },
+  ];
+
+  it('returns data unchanged when no channel declares scale.clip', () => {
+    const encoding: Encoding = {
+      x: { field: 'x', type: 'quantitative' },
+      y: { field: 'y', type: 'quantitative' },
+    };
+    const result = filterClippedDomains(data, encoding);
+    expect(result).toBe(data);
+    expect(result).toHaveLength(5);
+  });
+
+  it('filters rows outside the x-axis clipped domain', () => {
+    const encoding: Encoding = {
+      x: {
+        field: 'x',
+        type: 'quantitative',
+        scale: { domain: [0, 30], clip: true },
+      },
+      y: { field: 'y', type: 'quantitative' },
+    };
+    const result = filterClippedDomains(data, encoding);
+    expect(result).toEqual([
+      { x: 10, y: 20 },
+      { x: 25, y: 80 },
+    ]);
+  });
+
+  it('filters rows outside both x- and y-axis clipped domains', () => {
+    const encoding: Encoding = {
+      x: {
+        field: 'x',
+        type: 'quantitative',
+        scale: { domain: [0, 60], clip: true },
+      },
+      y: {
+        field: 'y',
+        type: 'quantitative',
+        scale: { domain: [0, 100], clip: true },
+      },
+    };
+    const result = filterClippedDomains(data, encoding);
+    expect(result).toEqual([
+      { x: 10, y: 20 },
+      { x: 25, y: 80 },
+    ]);
+  });
+
+  describe('categorical domains', () => {
+    const years = [
+      { year: '2019', pct: 32.4 },
+      { year: '2020', pct: 31.9 },
+      { year: '2021', pct: 33.9 },
+      { year: '2022', pct: 33.6 },
+    ];
+
+    it('keeps only rows whose value is in the domain set', () => {
+      const encoding: Encoding = {
+        x: {
+          field: 'year',
+          type: 'ordinal',
+          scale: { domain: ['2021', '2022'], clip: true },
+        },
+        y: { field: 'pct', type: 'quantitative' },
+      };
+      expect(filterClippedDomains(years, encoding)).toEqual([
+        { year: '2021', pct: 33.9 },
+        { year: '2022', pct: 33.6 },
+      ]);
+    });
+
+    it('matches numeric row values against a string domain', () => {
+      const numericYears = [
+        { year: 2020, pct: 31.9 },
+        { year: 2021, pct: 33.9 },
+      ];
+      const encoding: Encoding = {
+        x: {
+          field: 'year',
+          type: 'ordinal',
+          scale: { domain: ['2021'], clip: true },
+        },
+        y: { field: 'pct', type: 'quantitative' },
+      };
+      expect(filterClippedDomains(numericYears, encoding)).toEqual([{ year: 2021, pct: 33.9 }]);
+    });
+
+    it('does not treat a two-category domain as a numeric range', () => {
+      const encoding: Encoding = {
+        x: {
+          field: 'year',
+          type: 'ordinal',
+          // A range reading would keep 2020 and 2021 too; membership must not.
+          scale: { domain: ['2019', '2022'], clip: true },
+        },
+        y: { field: 'pct', type: 'quantitative' },
+      };
+      expect(filterClippedDomains(years, encoding)).toEqual([
+        { year: '2019', pct: 32.4 },
+        { year: '2022', pct: 33.6 },
+      ]);
+    });
+
+    it('passes data through when the channel has no clip', () => {
+      const encoding: Encoding = {
+        x: {
+          field: 'year',
+          type: 'ordinal',
+          scale: { domain: ['2021', '2022'] },
+        },
+        y: { field: 'pct', type: 'quantitative' },
+      };
+      expect(filterClippedDomains(years, encoding)).toBe(years);
+    });
+  });
+});

package/src/compile/__tests__/fill-patterns.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Fill pattern assignment (mark.fillPattern: 'auto').
+ *
+ * Locks the deterministic pattern-to-series assignment, the opt-in gate,
+ * and the minimum-area rule for thin marks.
+ */
+
+import type { ChartSpec, RectMark } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { compileChart } from '../../compile';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const FOUR_SERIES_DATA = [
+  { quarter: 'Q1', source: 'Solar', twh: 30 },
+  { quarter: 'Q1', source: 'Wind', twh: 45 },
+  { quarter: 'Q1', source: 'Hydro', twh: 25 },
+  { quarter: 'Q1', source: 'Gas', twh: 60 },
+  { quarter: 'Q2', source: 'Solar', twh: 35 },
+  { quarter: 'Q2', source: 'Wind', twh: 50 },
+  { quarter: 'Q2', source: 'Hydro', twh: 22 },
+  { quarter: 'Q2', source: 'Gas', twh: 55 },
+];
+
+function stackedSpec(fillPattern?: 'auto' | 'none'): ChartSpec {
+  return {
+    mark: { type: 'bar', ...(fillPattern ? { fillPattern } : {}) },
+    data: FOUR_SERIES_DATA,
+    encoding: {
+      x: { field: 'quarter', type: 'nominal' },
+      y: { field: 'twh', type: 'quantitative', stack: 'zero' },
+      color: { field: 'source', type: 'nominal' },
+    },
+  };
+}
+
+const OPTS = { width: 600, height: 400 };
+
+function rectMarks(spec: ChartSpec): RectMark[] {
+  return compileChart(spec, OPTS).marks.filter((m): m is RectMark => m.type === 'rect');
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('applyFillPatterns via compileChart', () => {
+  it('assigns four distinct patterns to a four-series stacked bar', () => {
+    const rects = rectMarks(stackedSpec('auto'));
+    expect(rects.length).toBeGreaterThan(0);
+
+    const byColor = new Map<string, string>();
+    for (const rect of rects) {
+      expect(rect.pattern).toBeDefined();
+      byColor.set(String(rect.fill), rect.pattern!.type);
+    }
+    // 4 series -> 4 distinct fills -> 4 distinct pattern shapes
+    expect(byColor.size).toBe(4);
+    expect(new Set(byColor.values()).size).toBe(4);
+    expect([...byColor.values()].sort()).toEqual(
+      ['crosshatch', 'diagonal', 'dot', 'vertical'].sort(),
+    );
+  });
+
+  it('is deterministic across repeat compiles', () => {
+    const first = rectMarks(stackedSpec('auto')).map((r) => r.pattern);
+    const second = rectMarks(stackedSpec('auto')).map((r) => r.pattern);
+    expect(second).toEqual(first);
+  });
+
+  it('picks a contrast-aware line color for each pattern', () => {
+    for (const rect of rectMarks(stackedSpec('auto'))) {
+      expect(['#ffffff', '#111111']).toContain(rect.pattern!.line);
+      expect(rect.pattern!.base).toBe(rect.fill);
+    }
+  });
+
+  it('does nothing by default or with fillPattern: none', () => {
+    for (const rect of rectMarks(stackedSpec())) {
+      expect(rect.pattern).toBeUndefined();
+    }
+    for (const rect of rectMarks(stackedSpec('none'))) {
+      expect(rect.pattern).toBeUndefined();
+    }
+  });
+
+  it('minimum-area rule: thin segments keep their solid fill', () => {
+    // Tiny values force sub-12px stacked segments at 400px height.
+    const thinData = FOUR_SERIES_DATA.map((row) =>
+      row.source === 'Hydro' ? { ...row, twh: 0.5 } : row,
+    );
+    const spec = { ...stackedSpec('auto'), data: thinData };
+    const rects = rectMarks(spec);
+
+    const thin = rects.filter((r) => Math.min(r.width, r.height) < 12);
+    const thick = rects.filter((r) => Math.min(r.width, r.height) >= 12);
+    expect(thin.length).toBeGreaterThan(0);
+    expect(thick.length).toBeGreaterThan(0);
+    for (const rect of thin) expect(rect.pattern).toBeUndefined();
+    for (const rect of thick) expect(rect.pattern).toBeDefined();
+  });
+
+  it('assignment does not shift when individual marks are too small', () => {
+    // Same series order, one series squeezed below the minimum extent:
+    // surviving patterns keep the same shape per series color.
+    const thinData = FOUR_SERIES_DATA.map((row) =>
+      row.source === 'Wind' ? { ...row, twh: 0.5 } : row,
+    );
+    const base = rectMarks(stackedSpec('auto'));
+    const squeezed = rectMarks({ ...stackedSpec('auto'), data: thinData });
+
+    const patternByFill = (rects: RectMark[]) => {
+      const map = new Map<string, string>();
+      for (const r of rects) {
+        if (r.pattern) map.set(String(r.fill), r.pattern.type);
+      }
+      return map;
+    };
+
+    const baseMap = patternByFill(base);
+    for (const [fill, type] of patternByFill(squeezed)) {
+      expect(baseMap.get(fill)).toBe(type);
+    }
+  });
+});
+
+describe('fill patterns on arcs', () => {
+  it('patterns pie slices and skips slivers', () => {
+    const spec: ChartSpec = {
+      mark: { type: 'arc', fillPattern: 'auto' },
+      data: [
+        { browser: 'Chrome', share: 64 },
+        { browser: 'Safari', share: 20 },
+        { browser: 'Edge', share: 15 },
+        { browser: 'Other', share: 0.4 },
+      ],
+      encoding: {
+        color: { field: 'browser', type: 'nominal' },
+        y: { field: 'share', type: 'quantitative' },
+      },
+    };
+    const layout = compileChart(spec, OPTS);
+    const arcs = layout.marks.filter((m) => m.type === 'arc');
+    expect(arcs.length).toBe(4);
+
+    const patterned = arcs.filter((a) => a.pattern);
+    const solid = arcs.filter((a) => !a.pattern);
+    // The 0.4% sliver falls under the minimum-area rule.
+    expect(patterned.length).toBe(3);
+    expect(solid.length).toBe(1);
+  });
+});

package/src/compile/__tests__/size-scale.test.ts

@@ -0,0 +1,108 @@
+import type { EncodingChannel } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { buildSizeScale } from '../size-scale';
+
+const DATA = [{ v: 1 }, { v: 4 }, { v: 9 }];
+const SQRT = { curve: 'sqrt' as const, range: [3, 30] as [number, number] };
+const LINEAR = { curve: 'linear' as const, range: [11, 32] as [number, number] };
+
+const size = (extra: Partial<EncodingChannel> = {}): EncodingChannel =>
+  ({ field: 'v', type: 'quantitative', ...extra }) as EncodingChannel;
+
+describe('buildSizeScale', () => {
+  it('returns null when there is no size encoding', () => {
+    expect(buildSizeScale(undefined, DATA, SQRT)).toBeNull();
+  });
+
+  it('fits the domain to the data extent and the range to the default', () => {
+    const resolved = buildSizeScale(size(), DATA, SQRT);
+    expect(resolved?.domain).toEqual([1, 9]);
+    expect(resolved?.range).toEqual([3, 30]);
+    expect(resolved?.field).toBe('v');
+  });
+
+  it('maps circles by area (sqrt), not by radius', () => {
+    const { scale } = buildSizeScale(size(), DATA, SQRT)!;
+    // Endpoints pin to the range.
+    expect(scale(1)).toBeCloseTo(3, 5);
+    expect(scale(9)).toBeCloseTo(30, 5);
+    // The midpoint of a sqrt scale sits ABOVE the linear midpoint (16.5):
+    // r = 3 + 27 * (sqrt(4)-sqrt(1)) / (sqrt(9)-sqrt(1)) = 16.5 -- for v=4
+    // that lands exactly on the linear midpoint by coincidence of 1/4/9, so
+    // check a value where the two genuinely diverge.
+    const linearAt6 = 3 + 27 * ((6 - 1) / (9 - 1)); // 19.875
+    expect(scale(6)).toBeGreaterThan(linearAt6);
+  });
+
+  it('maps glyphs by height (linear)', () => {
+    const { scale } = buildSizeScale(size(), DATA, LINEAR)!;
+    expect(scale(1)).toBeCloseTo(11, 5);
+    expect(scale(9)).toBeCloseTo(32, 5);
+    // Exactly proportional: no sqrt bulge.
+    expect(scale(5)).toBeCloseTo(11 + (32 - 11) * ((5 - 1) / (9 - 1)), 5);
+  });
+
+  it('lets an explicit scale.domain override the data extent', () => {
+    const resolved = buildSizeScale(size({ scale: { domain: [0, 100] } }), DATA, SQRT);
+    expect(resolved?.domain).toEqual([0, 100]);
+  });
+
+  it('lets an explicit scale.range override the default magnitudes', () => {
+    const resolved = buildSizeScale(size({ scale: { range: [5, 12] } }), DATA, SQRT);
+    expect(resolved?.range).toEqual([5, 12]);
+    expect(resolved?.scale(1)).toBeCloseTo(5, 5);
+    expect(resolved?.scale(9)).toBeCloseTo(12, 5);
+  });
+
+  it('clamps data outside an explicit domain to the range endpoints', () => {
+    // This is why a size legend must key the DOMAIN, not the data extent: every
+    // datum above domain[1] renders at max magnitude and is indistinguishable.
+    const { scale } = buildSizeScale(size({ scale: { domain: [0, 5] } }), DATA, SQRT)!;
+    expect(scale(9)).toBeCloseTo(scale(5), 5);
+    expect(scale(-100)).toBeCloseTo(scale(0), 5);
+  });
+
+  it('returns null for a degenerate domain (every value identical)', () => {
+    // A zero-width domain maps every datum to range[0]. There is no magnitude
+    // being encoded, so the caller falls back to its static default rather than
+    // rendering a field of identical minimum-size marks.
+    expect(buildSizeScale(size(), [{ v: 7 }, { v: 7 }], SQRT)).toBeNull();
+  });
+
+  it('returns null when no value is finite', () => {
+    expect(buildSizeScale(size(), [{ v: 'x' }, { v: null }], SQRT)).toBeNull();
+  });
+
+  it('ignores non-finite rows when fitting the domain', () => {
+    const resolved = buildSizeScale(size(), [{ v: 1 }, { v: 'nope' }, { v: 9 }], SQRT);
+    expect(resolved?.domain).toEqual([1, 9]);
+  });
+
+  it('treats a null hole as absent data, not as a zero', () => {
+    // `Number(null)` is a finite 0, so a hole that reaches the extent silently
+    // drags the domain floor to zero and rescales every genuine mark.
+    const resolved = buildSizeScale(size(), [{ v: 10 }, { v: 20 }, { v: null }], SQRT);
+    expect(resolved?.domain).toEqual([10, 20]);
+  });
+
+  it('treats an empty string the same way (Number("") is also 0)', () => {
+    const resolved = buildSizeScale(size(), [{ v: 10 }, { v: 20 }, { v: '' }], SQRT);
+    expect(resolved?.domain).toEqual([10, 20]);
+  });
+
+  it('returns null when the field is absent from every row', () => {
+    // `min([])`/`max([])` are undefined; a `?? 0` / `?? 1` fallback would
+    // fabricate a live [0, 1] scale out of data that encodes no size at all.
+    expect(buildSizeScale(size(), [{ other: 1 }, { other: 2 }], SQRT)).toBeNull();
+  });
+
+  it('returns null on empty data', () => {
+    expect(buildSizeScale(size(), [], SQRT)).toBeNull();
+  });
+
+  it('honours an explicit domain even when the data has no usable extent', () => {
+    // The domain is the author's, not the data's, so it stands on its own.
+    const resolved = buildSizeScale(size({ scale: { domain: [0, 100] } }), [{ v: null }], SQRT);
+    expect(resolved?.domain).toEqual([0, 100]);
+  });
+});

package/src/compile/__tests__/watermark-obstacle.test.ts

@@ -0,0 +1,93 @@
+import type { AxisLayout, Rect, ResolvedChrome, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { BRAND_RESERVE_WIDTH, resolveTheme } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import type { AxesResult } from '../../layout/axes';
+import type { LayoutDimensions } from '../../layout/dimensions';
+import { computeWatermarkObstacle } from '../watermark-obstacle';
+
+const theme: ResolvedTheme = resolveTheme();
+
+function makeDims(overrides: Partial<LayoutDimensions> = {}): LayoutDimensions {
+  const total: Rect = { x: 0, y: 0, width: 800, height: 500 };
+  const chartArea: Rect = { x: 60, y: 80, width: 700, height: 360 };
+  const chrome: ResolvedChrome = {
+    topHeight: 80,
+    bottomHeight: 40,
+  } as ResolvedChrome;
+  return {
+    total,
+    chartArea,
+    chrome,
+    margins: { top: 80, right: 40, bottom: 40, left: 60 },
+    theme,
+    ...overrides,
+  };
+}
+
+function makeAxis(label?: string): AxisLayout {
+  return {
+    ticks: [],
+    gridlines: [],
+    label,
+    tickLabelStyle: {
+      fontFamily: theme.fonts.family,
+      fontSize: 12,
+      fontWeight: 400,
+      fill: '#000',
+      lineHeight: 1.2,
+    },
+    start: { x: 0, y: 0 },
+    end: { x: 100, y: 0 },
+  };
+}
+
+describe('computeWatermarkObstacle', () => {
+  it('returns null when watermark is disabled', () => {
+    const dims = makeDims();
+    const axes: AxesResult = { x: makeAxis(), y: makeAxis() };
+    expect(computeWatermarkObstacle(dims, false, axes, theme)).toBeNull();
+  });
+
+  it('sits below the x-axis when no bottom chrome is present', () => {
+    const dims = makeDims();
+    const axes: AxesResult = { x: makeAxis('value'), y: makeAxis() };
+    const rect = computeWatermarkObstacle(dims, true, axes, theme);
+    expect(rect).not.toBeNull();
+    // Right-aligned: total.width - padding - BRAND_RESERVE_WIDTH
+    expect(rect!.x).toBe(dims.total.width - theme.spacing.padding - BRAND_RESERVE_WIDTH);
+    expect(rect!.width).toBe(BRAND_RESERVE_WIDTH);
+    expect(rect!.height).toBe(30);
+    // Watermark sits below chart area, offset by x-axis extent + chartToFooter
+    const expectedY = dims.chartArea.y + dims.chartArea.height + 48 + theme.spacing.chartToFooter;
+    expect(rect!.y).toBe(expectedY);
+  });
+
+  it('aligns with bottom chrome when a source element is present', () => {
+    const sourceY = 20;
+    const dims = makeDims({
+      chrome: {
+        topHeight: 80,
+        bottomHeight: 40,
+        source: {
+          text: 'Source: Test',
+          x: 10,
+          y: sourceY,
+          maxWidth: 500,
+          style: {
+            fontFamily: theme.fonts.family,
+            fontSize: 10,
+            fontWeight: 400,
+            fill: '#666',
+            lineHeight: 1.2,
+          },
+        },
+      } as ResolvedChrome,
+    });
+    const axes: AxesResult = { x: makeAxis(), y: makeAxis() };
+    const rect = computeWatermarkObstacle(dims, true, axes, theme);
+    expect(rect).not.toBeNull();
+    // With axis present but no label, extent is 26.
+    // Y is chartArea.y + chartArea.height + 26 + sourceY
+    expect(rect!.y).toBe(dims.chartArea.y + dims.chartArea.height + 26 + sourceY);
+  });
+});

package/src/compile/color-scale-range.ts

@@ -0,0 +1,101 @@
+/**
+ * Apply the theme palette as the color scale range when no explicit range was provided.
+ *
+ * Sequential scales take the first/last stops of the first sequential palette
+ * (or the categorical endpoints as a fallback). Categorical scales get the
+ * full categorical palette. A user-provided `encoding.color.scale.range`
+ * always wins.
+ *
+ * When `highlight` is non-empty, highlighted series get sequential palette
+ * colors and muted series get a neutral gray.
+ *
+ * When `theme.seriesStrategy` is `'accent-neutral'`, low-cardinality
+ * charts use accent + neutral grays instead of the full palette.
+ */
+
+import { ACHROMATIC_RAMP, type Encoding, type ResolvedTheme } from '@opendata-ai/openchart-core';
+import type { ScaleLinear, ScaleOrdinal, ScaleQuantile } from 'd3-scale';
+import type { ResolvedScales } from '../layout/scales';
+import { sampleRampColors } from '../legend/continuous';
+
+/** Neutral gray applied to muted (non-highlighted) series. */
+const MUTED_COLOR = '#bfc3c8';
+
+/**
+ * Resolve the categorical color range for a color-scale domain.
+ *
+ * Single source of truth for categorical color assignment: the ordinal scale
+ * (which colors the marks) and the legend (which colors the swatches) both go
+ * through this, so highlight muting and the accent-neutral series strategy
+ * stay in sync. Callers pass the domain in the same order the scale uses.
+ *
+ * The result is a d3 ordinal *range*, so callers index it the way d3 does:
+ * `colors[domainIndex % colors.length]`. In the pass-through cases the full
+ * palette comes back unsliced (d3 cycles it), matching the range the scale
+ * carried before this was factored out.
+ */
+export function categoricalColorsForDomain(
+  domain: string[],
+  theme: ResolvedTheme,
+  highlight?: string[],
+): string[] {
+  const palette = theme.colors.categorical;
+
+  if (highlight && highlight.length > 0) {
+    const highlightSet = new Set(highlight);
+    return domain.map((v, i) => (highlightSet.has(v) ? palette[i % palette.length] : MUTED_COLOR));
+  }
+
+  const strategy = theme.seriesStrategy ?? 'palette';
+  if (strategy !== 'accent-neutral') return palette;
+
+  const count = domain.length;
+  if (count <= 1) return [palette[0]];
+  if (count > 4) return palette;
+
+  // Prominence tracks contrast against the surface: on dark canvases the
+  // brightest gray reads strongest, on light canvases the darkest.
+  const neutrals = theme.isDark
+    ? [ACHROMATIC_RAMP.fgMuted, ACHROMATIC_RAMP.fgSubtle, ACHROMATIC_RAMP.fgFaint]
+    : [ACHROMATIC_RAMP.fgFaint, ACHROMATIC_RAMP.fgSubtle, ACHROMATIC_RAMP.fgMuted];
+  return domain.map((_, i) => (i === 0 ? palette[0] : neutrals[(i - 1) % neutrals.length]));
+}
+
+/** Mutates `scales.color.scale.range` in place when no explicit palette was set. */
+export function applyColorScaleRange(
+  scales: ResolvedScales,
+  encoding: Encoding,
+  theme: ResolvedTheme,
+  highlight?: string[],
+): void {
+  if (!scales.color) return;
+
+  const hasExplicitRange = !!(
+    encoding.color &&
+    'field' in encoding.color &&
+    (encoding.color.scale?.range as string[] | undefined)?.length
+  );
+  if (hasExplicitRange) return;
+
+  if (scales.color.type === 'sequential') {
+    const seqStops = Object.values(theme.colors.sequential)[0] ?? theme.colors.categorical;
+    (scales.color.scale as unknown as ScaleLinear<string, string>).range([
+      seqStops[0],
+      seqStops[seqStops.length - 1],
+    ]);
+  } else if (
+    scales.color.type === 'quantile' ||
+    scales.color.type === 'quantize' ||
+    scales.color.type === 'threshold'
+  ) {
+    // Binned color scales: replace the placeholder colors with the theme's
+    // sequential ramp, sampled to the class count. Same ramp the gradient
+    // legend and continuous marks use.
+    const seqStops = Object.values(theme.colors.sequential)[0] ?? theme.colors.categorical;
+    const scale = scales.color.scale as unknown as ScaleQuantile<string>;
+    scale.range(sampleRampColors(seqStops, scale.range().length));
+  } else {
+    const ordinalScale = scales.color.scale as ScaleOrdinal<string, string>;
+    ordinalScale.range(categoricalColorsForDomain(ordinalScale.domain(), theme, highlight));
+  }
+}