@opendata-ai/openchart-core 2.0.0

package/src/colors/colorblind.ts

@@ -0,0 +1,122 @@
+/**
+ * Color blindness simulation and palette distinguishability checks.
+ *
+ * Uses Brettel, Vienot, and Mollon (1997) simulation matrices for
+ * protanopia, deuteranopia, and tritanopia.
+ *
+ * These are approximations suitable for checking palette accessibility,
+ * not medical-grade simulations.
+ */
+
+import { rgb } from 'd3-color';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** The three common types of color vision deficiency. */
+export type ColorBlindnessType = 'protanopia' | 'deuteranopia' | 'tritanopia';
+
+// ---------------------------------------------------------------------------
+// Simulation matrices
+// ---------------------------------------------------------------------------
+
+// 3x3 color transformation matrices for each deficiency type.
+// Applied in linear RGB space to simulate how colors appear.
+// Source: Brettel, Vienot & Mollon (1997), simplified.
+
+type Matrix3x3 = readonly [
+  readonly [number, number, number],
+  readonly [number, number, number],
+  readonly [number, number, number],
+];
+
+const PROTAN_MATRIX: Matrix3x3 = [
+  [0.567, 0.433, 0.0],
+  [0.558, 0.442, 0.0],
+  [0.0, 0.242, 0.758],
+];
+
+const DEUTAN_MATRIX: Matrix3x3 = [
+  [0.625, 0.375, 0.0],
+  [0.7, 0.3, 0.0],
+  [0.0, 0.3, 0.7],
+];
+
+const TRITAN_MATRIX: Matrix3x3 = [
+  [0.95, 0.05, 0.0],
+  [0.0, 0.433, 0.567],
+  [0.0, 0.475, 0.525],
+];
+
+const MATRICES: Record<ColorBlindnessType, Matrix3x3> = {
+  protanopia: PROTAN_MATRIX,
+  deuteranopia: DEUTAN_MATRIX,
+  tritanopia: TRITAN_MATRIX,
+};
+
+// ---------------------------------------------------------------------------
+// sRGB linearization helpers
+// ---------------------------------------------------------------------------
+
+function linearize(v: number): number {
+  const s = v / 255;
+  return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+}
+
+function delinearize(v: number): number {
+  const s = v <= 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055;
+  return Math.round(Math.max(0, Math.min(255, s * 255)));
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Simulate how a color appears under a given color blindness type.
+ * Returns a hex color string.
+ */
+export function simulateColorBlindness(color: string, type: ColorBlindnessType): string {
+  const c = rgb(color);
+  if (c == null) return color;
+
+  const lin = [linearize(c.r), linearize(c.g), linearize(c.b)];
+  const m = MATRICES[type];
+
+  const r = m[0][0] * lin[0] + m[0][1] * lin[1] + m[0][2] * lin[2];
+  const g = m[1][0] * lin[0] + m[1][1] * lin[1] + m[1][2] * lin[2];
+  const b = m[2][0] * lin[0] + m[2][1] * lin[1] + m[2][2] * lin[2];
+
+  return rgb(delinearize(r), delinearize(g), delinearize(b)).formatHex();
+}
+
+/**
+ * Check if colors in a palette are distinguishable under a given
+ * color blindness type.
+ *
+ * Uses a minimum perceptual distance threshold in simulated space.
+ * Returns true if all pairs of colors are sufficiently different.
+ */
+export function checkPaletteDistinguishability(
+  colors: string[],
+  type: ColorBlindnessType,
+  minDistance = 30,
+): boolean {
+  const simulated = colors.map((c) => {
+    const s = rgb(simulateColorBlindness(c, type));
+    return s ? [s.r, s.g, s.b] : [0, 0, 0];
+  });
+
+  for (let i = 0; i < simulated.length; i++) {
+    for (let j = i + 1; j < simulated.length; j++) {
+      const dr = simulated[i][0] - simulated[j][0];
+      const dg = simulated[i][1] - simulated[j][1];
+      const db = simulated[i][2] - simulated[j][2];
+      const dist = Math.sqrt(dr * dr + dg * dg + db * db);
+      if (dist < minDistance) return false;
+    }
+  }
+
+  return true;
+}

package/src/colors/contrast.ts

@@ -0,0 +1,94 @@
+/**
+ * WCAG contrast ratio utilities.
+ *
+ * Uses d3-color for color space parsing and manipulation.
+ * All functions accept CSS color strings (hex, rgb, hsl, named colors).
+ */
+
+import { rgb } from 'd3-color';
+
+// ---------------------------------------------------------------------------
+// Relative luminance (WCAG 2.1)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the relative luminance of a color per WCAG 2.1 definition.
+ * https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+ */
+function relativeLuminance(color: string): number {
+  const c = rgb(color);
+  if (c == null) return 0;
+
+  const srgb = [c.r / 255, c.g / 255, c.b / 255];
+  const linear = srgb.map((v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * linear[0] + 0.7152 * linear[1] + 0.0722 * linear[2];
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the WCAG contrast ratio between two colors.
+ * Returns a value between 1 (identical) and 21 (black on white).
+ */
+export function contrastRatio(fg: string, bg: string): number {
+  const l1 = relativeLuminance(fg);
+  const l2 = relativeLuminance(bg);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Check if two colors meet WCAG AA contrast requirements.
+ * Normal text: 4.5:1, large text (18px+ bold or 24px+): 3:1.
+ */
+export function meetsAA(fg: string, bg: string, largeText = false): boolean {
+  const ratio = contrastRatio(fg, bg);
+  return largeText ? ratio >= 3 : ratio >= 4.5;
+}
+
+/**
+ * Find an accessible variant of `baseColor` against `bg`.
+ *
+ * Preserves the hue and saturation of baseColor but adjusts lightness
+ * until the target contrast ratio is met. Returns the original color
+ * if it already meets the target.
+ */
+export function findAccessibleColor(baseColor: string, bg: string, targetRatio = 4.5): string {
+  if (contrastRatio(baseColor, bg) >= targetRatio) {
+    return baseColor;
+  }
+
+  const c = rgb(baseColor);
+  if (c == null) return baseColor;
+
+  const bgLum = relativeLuminance(bg);
+  // Determine direction: darken if bg is light, lighten if bg is dark.
+  const bgIsLight = bgLum > 0.5;
+
+  // Binary search for the lightness adjustment that hits the target ratio.
+  let lo = 0;
+  let hi = 1;
+  let best = baseColor;
+
+  for (let i = 0; i < 20; i++) {
+    const mid = (lo + hi) / 2;
+    const adjusted = bgIsLight
+      ? rgb(c.r * (1 - mid), c.g * (1 - mid), c.b * (1 - mid))
+      : rgb(c.r + (255 - c.r) * mid, c.g + (255 - c.g) * mid, c.b + (255 - c.b) * mid);
+
+    const hex = adjusted.formatHex();
+    const ratio = contrastRatio(hex, bg);
+
+    if (ratio >= targetRatio) {
+      best = hex;
+      hi = mid; // try less adjustment
+    } else {
+      lo = mid; // need more adjustment
+    }
+  }
+
+  return best;
+}

package/src/colors/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Color system barrel export.
+ */
+
+export type { ColorBlindnessType } from './colorblind';
+export {
+  checkPaletteDistinguishability,
+  simulateColorBlindness,
+} from './colorblind';
+
+export { contrastRatio, findAccessibleColor, meetsAA } from './contrast';
+export type {
+  CategoricalPalette,
+  DivergingPalette,
+  SequentialPalette,
+} from './palettes';
+export {
+  CATEGORICAL_PALETTE,
+  DIVERGING_BROWN_TEAL,
+  DIVERGING_PALETTES,
+  DIVERGING_RED_BLUE,
+  SEQUENTIAL_BLUE,
+  SEQUENTIAL_GREEN,
+  SEQUENTIAL_ORANGE,
+  SEQUENTIAL_PALETTES,
+  SEQUENTIAL_PURPLE,
+} from './palettes';

package/src/colors/palettes.ts

@@ -0,0 +1,118 @@
+/**
+ * Color palettes for @opendata-ai.
+ *
+ * Categorical palette is Infrographic-influenced with WCAG AA contrast
+ * for large text (3:1 ratio) on both light (#ffffff) and dark (#1a1a2e)
+ * backgrounds. Several colors do not meet the stricter 4.5:1 ratio
+ * required for normal-sized body text. This is acceptable because chart
+ * marks (bars, lines, areas, points) are large visual elements.
+ *
+ * Sequential palettes: 5-7 stops from light to dark.
+ * Diverging palettes: 7 stops with a neutral midpoint.
+ */
+
+// ---------------------------------------------------------------------------
+// Categorical
+// ---------------------------------------------------------------------------
+
+/**
+ * Default categorical palette. 10 visually distinct colors that meet
+ * WCAG AA contrast for large text (3:1) on both white and near-black
+ * backgrounds. Some colors fall below the 4.5:1 threshold for normal
+ * body text. Influenced by Infrographic's editorial palette with tweaks
+ * for accessibility and colorblind distinguishability.
+ */
+export const CATEGORICAL_PALETTE = [
+  '#1b7fa3', // teal-blue (primary)
+  '#c44e52', // warm red (secondary)
+  '#6a9f58', // softer green (tertiary)
+  '#d47215', // orange
+  '#507e79', // muted teal
+  '#9a6a8d', // purple
+  '#c4636b', // rose
+  '#9c755f', // brown
+  '#a88f22', // olive gold
+  '#858078', // warm gray
+] as const;
+
+export type CategoricalPalette = typeof CATEGORICAL_PALETTE;
+
+// ---------------------------------------------------------------------------
+// Sequential
+// ---------------------------------------------------------------------------
+
+/** Sequential palette definition: an array of color stops from light to dark. */
+export interface SequentialPalette {
+  readonly name: string;
+  readonly stops: readonly string[];
+}
+
+export const SEQUENTIAL_BLUE: SequentialPalette = {
+  name: 'blue',
+  stops: ['#deebf7', '#c6dbef', '#9ecae1', '#6baed6', '#3182bd', '#08519c'],
+} as const;
+
+export const SEQUENTIAL_GREEN: SequentialPalette = {
+  name: 'green',
+  stops: ['#e5f5e0', '#c7e9c0', '#a1d99b', '#74c476', '#31a354', '#006d2c'],
+} as const;
+
+export const SEQUENTIAL_ORANGE: SequentialPalette = {
+  name: 'orange',
+  stops: ['#fee6ce', '#fdd0a2', '#fdae6b', '#fd8d3c', '#e6550d', '#a63603'],
+} as const;
+
+export const SEQUENTIAL_PURPLE: SequentialPalette = {
+  name: 'purple',
+  stops: ['#efedf5', '#dadaeb', '#bcbddc', '#9e9ac8', '#756bb1', '#54278f'],
+} as const;
+
+/** All sequential palettes keyed by name. */
+export const SEQUENTIAL_PALETTES: Record<string, string[]> = {
+  blue: [...SEQUENTIAL_BLUE.stops],
+  green: [...SEQUENTIAL_GREEN.stops],
+  orange: [...SEQUENTIAL_ORANGE.stops],
+  purple: [...SEQUENTIAL_PURPLE.stops],
+};
+
+// ---------------------------------------------------------------------------
+// Diverging
+// ---------------------------------------------------------------------------
+
+/** Diverging palette definition: an array of color stops with a neutral midpoint. */
+export interface DivergingPalette {
+  readonly name: string;
+  readonly stops: readonly string[];
+}
+
+export const DIVERGING_RED_BLUE: DivergingPalette = {
+  name: 'redBlue',
+  stops: [
+    '#b2182b', // strong red
+    '#d6604d', // medium red
+    '#f4a582', // light red
+    '#f7f7f7', // neutral
+    '#92c5de', // light blue
+    '#4393c3', // medium blue
+    '#2166ac', // strong blue
+  ],
+} as const;
+
+export const DIVERGING_BROWN_TEAL: DivergingPalette = {
+  name: 'brownTeal',
+  stops: [
+    '#8c510a', // strong brown
+    '#bf812d', // medium brown
+    '#dfc27d', // light brown
+    '#f6e8c3', // neutral
+    '#80cdc1', // light teal
+    '#35978f', // medium teal
+    '#01665e', // strong teal
+  ],
+} as const;
+
+/** All diverging palettes keyed by name. */
+export const DIVERGING_PALETTES: Record<string, string[]> = {
+  redBlue: [...DIVERGING_RED_BLUE.stops],
+  brownTeal: [...DIVERGING_BROWN_TEAL.stops],
+};

package/src/helpers/__tests__/spec-builders.test.ts

@@ -0,0 +1,336 @@
+import { describe, expect, it } from 'vitest';
+import type { EncodingChannel } from '../../types/spec';
+import {
+  barChart,
+  columnChart,
+  dataTable,
+  inferFieldType,
+  lineChart,
+  pieChart,
+  scatterChart,
+} from '../spec-builders';
+
+// ---------------------------------------------------------------------------
+// Test data
+// ---------------------------------------------------------------------------
+
+const timeSeriesData = [
+  { date: '2020-01-01', value: 10, country: 'US' },
+  { date: '2021-01-01', value: 40, country: 'US' },
+  { date: '2020-01-01', value: 15, country: 'UK' },
+  { date: '2021-01-01', value: 35, country: 'UK' },
+];
+
+const categoricalData = [
+  { name: 'Apples', count: 50, price: 1.2 },
+  { name: 'Bananas', count: 30, price: 0.8 },
+  { name: 'Oranges', count: 45, price: 1.5 },
+];
+
+const numericData = [
+  { x: 1, y: 2, size: 10, group: 'A' },
+  { x: 3, y: 4, size: 20, group: 'B' },
+  { x: 5, y: 1, size: 15, group: 'A' },
+];
+
+const mixedData = [
+  { id: 1, name: 'Alice', score: 95, joined: '2020-03-15' },
+  { id: 2, name: 'Bob', score: 87, joined: '2021-07-22' },
+  { id: 3, name: 'Carol', score: 92, joined: '2019-11-01' },
+];
+
+// ---------------------------------------------------------------------------
+// inferFieldType
+// ---------------------------------------------------------------------------
+
+describe('inferFieldType', () => {
+  it('infers quantitative for number fields', () => {
+    expect(inferFieldType(categoricalData, 'count')).toBe('quantitative');
+    expect(inferFieldType(categoricalData, 'price')).toBe('quantitative');
+  });
+
+  it('infers temporal for ISO date strings', () => {
+    expect(inferFieldType(timeSeriesData, 'date')).toBe('temporal');
+  });
+
+  it('infers temporal for partial ISO dates (YYYY-MM format)', () => {
+    const data = [{ period: '2020-01' }, { period: '2020-02' }];
+    expect(inferFieldType(data, 'period')).toBe('temporal');
+  });
+
+  it('infers temporal for year-only strings (YYYY format)', () => {
+    const data = [{ year: '2020' }, { year: '2021' }];
+    expect(inferFieldType(data, 'year')).toBe('temporal');
+  });
+
+  it('infers nominal for plain string fields', () => {
+    expect(inferFieldType(categoricalData, 'name')).toBe('nominal');
+    expect(inferFieldType(timeSeriesData, 'country')).toBe('nominal');
+  });
+
+  it('infers nominal for mixed types', () => {
+    const data = [{ value: 10 }, { value: 'text' }];
+    expect(inferFieldType(data, 'value')).toBe('nominal');
+  });
+
+  it('handles null/undefined values gracefully', () => {
+    const data = [{ value: null }, { value: undefined }, { value: 42 }];
+    expect(inferFieldType(data, 'value')).toBe('quantitative');
+  });
+
+  it('handles Date objects as temporal', () => {
+    const data = [{ date: new Date('2020-01-01') }, { date: new Date('2021-01-01') }];
+    expect(inferFieldType(data, 'date')).toBe('temporal');
+  });
+
+  it('samples at most 20 values', () => {
+    // Create 100 items, all numbers. Should still work without issue.
+    const data = Array.from({ length: 100 }, (_, i) => ({ v: i }));
+    expect(inferFieldType(data, 'v')).toBe('quantitative');
+  });
+
+  it('returns nominal for empty data', () => {
+    expect(inferFieldType([], 'anything')).toBe('nominal');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// lineChart
+// ---------------------------------------------------------------------------
+
+describe('lineChart', () => {
+  it('creates a line chart spec with string field names', () => {
+    const spec = lineChart(timeSeriesData, 'date', 'value');
+
+    expect(spec.type).toBe('line');
+    expect(spec.data).toBe(timeSeriesData);
+    expect(spec.encoding.x).toEqual({ field: 'date', type: 'temporal' });
+    expect(spec.encoding.y).toEqual({ field: 'value', type: 'quantitative' });
+  });
+
+  it('accepts full EncodingChannel objects', () => {
+    const xChannel: EncodingChannel = {
+      field: 'date',
+      type: 'temporal',
+      axis: { label: 'Year' },
+    };
+    const yChannel: EncodingChannel = {
+      field: 'value',
+      type: 'quantitative',
+      scale: { zero: true },
+    };
+
+    const spec = lineChart(timeSeriesData, xChannel, yChannel);
+
+    expect(spec.encoding.x).toEqual(xChannel);
+    expect(spec.encoding.y).toEqual(yChannel);
+  });
+
+  it('includes color encoding from options', () => {
+    const spec = lineChart(timeSeriesData, 'date', 'value', {
+      color: 'country',
+    });
+
+    expect(spec.encoding.color).toEqual({ field: 'country', type: 'nominal' });
+  });
+
+  it('passes through chrome and annotations', () => {
+    const spec = lineChart(timeSeriesData, 'date', 'value', {
+      chrome: { title: 'GDP Growth' },
+      annotations: [{ type: 'refline', y: 0, label: 'Zero' }],
+    });
+
+    expect(spec.chrome).toEqual({ title: 'GDP Growth' });
+    expect(spec.annotations).toHaveLength(1);
+  });
+
+  it('passes through theme and darkMode', () => {
+    const spec = lineChart(timeSeriesData, 'date', 'value', {
+      theme: { borderRadius: 8 },
+      darkMode: 'auto',
+    });
+
+    expect(spec.theme).toEqual({ borderRadius: 8 });
+    expect(spec.darkMode).toBe('auto');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// barChart
+// ---------------------------------------------------------------------------
+
+describe('barChart', () => {
+  it('maps category to y-axis and value to x-axis', () => {
+    const spec = barChart(categoricalData, 'name', 'count');
+
+    expect(spec.type).toBe('bar');
+    // Bar chart convention: category on y, value on x
+    expect(spec.encoding.y).toEqual({ field: 'name', type: 'nominal' });
+    expect(spec.encoding.x).toEqual({ field: 'count', type: 'quantitative' });
+  });
+
+  it('accepts full channel objects', () => {
+    const catChannel: EncodingChannel = {
+      field: 'name',
+      type: 'ordinal',
+      axis: { label: 'Fruit' },
+    };
+
+    const spec = barChart(categoricalData, catChannel, 'count');
+
+    expect(spec.encoding.y).toEqual(catChannel);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// columnChart
+// ---------------------------------------------------------------------------
+
+describe('columnChart', () => {
+  it('creates a column chart spec with x and y', () => {
+    const spec = columnChart(categoricalData, 'name', 'count');
+
+    expect(spec.type).toBe('column');
+    expect(spec.encoding.x).toEqual({ field: 'name', type: 'nominal' });
+    expect(spec.encoding.y).toEqual({ field: 'count', type: 'quantitative' });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// pieChart
+// ---------------------------------------------------------------------------
+
+describe('pieChart', () => {
+  it('maps category to color channel and value to y', () => {
+    const spec = pieChart(categoricalData, 'name', 'count');
+
+    expect(spec.type).toBe('pie');
+    // Pie chart convention: value on y, category on color, no x
+    expect(spec.encoding.y).toEqual({ field: 'count', type: 'quantitative' });
+    expect(spec.encoding.color).toEqual({ field: 'name', type: 'nominal' });
+    expect(spec.encoding.x).toBeUndefined();
+  });
+
+  it('includes size encoding when specified', () => {
+    const spec = pieChart(numericData, 'group', 'y', { size: 'size' });
+
+    expect(spec.encoding.size).toEqual({ field: 'size', type: 'quantitative' });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// scatterChart
+// ---------------------------------------------------------------------------
+
+describe('scatterChart', () => {
+  it('creates a scatter chart with both axes quantitative', () => {
+    const spec = scatterChart(numericData, 'x', 'y');
+
+    expect(spec.type).toBe('scatter');
+    expect(spec.encoding.x).toEqual({ field: 'x', type: 'quantitative' });
+    expect(spec.encoding.y).toEqual({ field: 'y', type: 'quantitative' });
+  });
+
+  it('supports color and size encoding', () => {
+    const spec = scatterChart(numericData, 'x', 'y', {
+      color: 'group',
+      size: 'size',
+    });
+
+    expect(spec.encoding.color).toEqual({ field: 'group', type: 'nominal' });
+    expect(spec.encoding.size).toEqual({ field: 'size', type: 'quantitative' });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// dataTable
+// ---------------------------------------------------------------------------
+
+describe('dataTable', () => {
+  it('auto-generates columns from data keys', () => {
+    const spec = dataTable(categoricalData);
+
+    expect(spec.type).toBe('table');
+    expect(spec.data).toBe(categoricalData);
+    expect(spec.columns).toHaveLength(3);
+    expect(spec.columns[0]).toEqual({ key: 'name', label: 'name', align: 'left' });
+    expect(spec.columns[1]).toEqual({ key: 'count', label: 'count', align: 'right' });
+    expect(spec.columns[2]).toEqual({ key: 'price', label: 'price', align: 'right' });
+  });
+
+  it('uses provided columns instead of auto-generating', () => {
+    const columns = [
+      { key: 'name', label: 'Fruit Name' },
+      { key: 'count', label: 'Quantity', format: ',.0f' },
+    ];
+    const spec = dataTable(categoricalData, { columns });
+
+    expect(spec.columns).toBe(columns);
+    expect(spec.columns).toHaveLength(2);
+  });
+
+  it('right-aligns numeric columns in auto-generated config', () => {
+    const spec = dataTable(mixedData);
+
+    const idCol = spec.columns.find((c) => c.key === 'id');
+    const scoreCol = spec.columns.find((c) => c.key === 'score');
+    const nameCol = spec.columns.find((c) => c.key === 'name');
+
+    expect(idCol?.align).toBe('right');
+    expect(scoreCol?.align).toBe('right');
+    expect(nameCol?.align).toBe('left');
+  });
+
+  it('passes through all table options', () => {
+    const spec = dataTable(categoricalData, {
+      rowKey: 'name',
+      chrome: { title: 'Fruit Data' },
+      search: true,
+      pagination: { pageSize: 10 },
+      stickyFirstColumn: true,
+      compact: true,
+      darkMode: 'auto',
+    });
+
+    expect(spec.rowKey).toBe('name');
+    expect(spec.chrome).toEqual({ title: 'Fruit Data' });
+    expect(spec.search).toBe(true);
+    expect(spec.pagination).toEqual({ pageSize: 10 });
+    expect(spec.stickyFirstColumn).toBe(true);
+    expect(spec.compact).toBe(true);
+    expect(spec.darkMode).toBe('auto');
+  });
+
+  it('returns empty columns for empty data', () => {
+    const spec = dataTable([]);
+
+    expect(spec.columns).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Mixed field ref (string vs object) across builders
+// ---------------------------------------------------------------------------
+
+describe('mixed FieldRef usage', () => {
+  it('allows mixing string and object field refs', () => {
+    const yChannel: EncodingChannel = {
+      field: 'value',
+      type: 'quantitative',
+      aggregate: 'mean',
+      axis: { label: 'Average Value', format: ',.1f' },
+    };
+
+    const spec = lineChart(timeSeriesData, 'date', yChannel, {
+      color: { field: 'country', type: 'nominal' },
+    });
+
+    // x was a string, so type was inferred
+    expect(spec.encoding.x?.type).toBe('temporal');
+    // y was a full object, so it's passed through
+    expect(spec.encoding.y?.aggregate).toBe('mean');
+    expect(spec.encoding.y?.axis?.label).toBe('Average Value');
+    // color was a full object
+    expect(spec.encoding.color?.type).toBe('nominal');
+  });
+});